dsh-autorestart 0.5.0 → 0.6.1

package/lib/checkpoint.js

@@ -106,6 +106,7 @@ const TOP_LEVEL_KEYS = new Set([
   'parkedGoals',
   'disarmedGoals',
   'seenFeatureVersions',
+  'sleep',
   'updatedAt',
 ]);
 
@@ -174,6 +175,7 @@ export function createEmptyState(now = Date.now()) {
     restart: null,
     sessions: {},
     seenFeatureVersions: {},
+    sleep: null,
     updatedAt: now,
   };
 }
@@ -306,6 +308,32 @@ function normalizeSeenFeatureVersions(raw) {
   return { seenFeatureVersions, changed };
 }
 
+/**
+ * Normalize the recorded shutdown intent.
+ *
+ * The intent is the user's "shut the machine down when the work is done" — it
+ * has to survive a restart, so it lives in the checkpoint file. A record that
+ * is broken is DROPPED: asking the user once more is much better than a
+ * machine that switches itself off for ever because of a half-written file.
+ *
+ * @param {unknown} raw
+ * @returns {{ sleep: { armed: true, armedAt: number, countdownSeconds: number|null }|null, changed: boolean }}
+ */
+function normalizeSleep(raw) {
+  if (raw == null) return { sleep: null, changed: false };
+  if (!isObject(raw)) return { sleep: null, changed: true };
+  if (raw.armed !== true) return { sleep: null, changed: true };
+  const armedAt = isFiniteNumber(raw.armedAt) ? raw.armedAt : null;
+  if (armedAt === null) return { sleep: null, changed: true };
+  const countdownSeconds = isFiniteNumber(raw.countdownSeconds) && raw.countdownSeconds >= 0
+    ? Math.trunc(raw.countdownSeconds)
+    : null;
+  return {
+    sleep: { armed: true, armedAt, countdownSeconds },
+    changed: raw.countdownSeconds !== countdownSeconds,
+  };
+}
+
 /**
  * Normalize the handoff record of a session: `{ handedOffTo, handoffAt, carriedChars }`.
  * A missing record stays `null`; a corrupt one is dropped instead of being thrown on.
@@ -574,6 +602,14 @@ export function normalizeState(raw, now = Date.now()) {
     if (seen.changed) repaired = true;
   }
 
+  // The recorded shutdown intent: it has to survive a restart, so the machine
+  // goes off AFTER the restart and the work that resumed with it.
+  if (raw.sleep != null) {
+    const sleep = normalizeSleep(raw.sleep);
+    state.sleep = sleep.sleep;
+    if (sleep.changed) repaired = true;
+  }
+
   return { state, repaired };
 }
 
@@ -1235,6 +1271,48 @@ export function cancelRestart(state, { now = Date.now() } = {}) {
   return state;
 }
 
+/**
+ * Record the shutdown intent: "switch the machine off when the work is done".
+ *
+ * The intent lives in the checkpoint file, so it survives a restart: a
+ * shutdown that is asked for while a restart is pending waits for that
+ * restart (and for the sessions that resume with it) before the machine goes
+ * off.
+ *
+ * Mutates `state` in place and returns it.
+ *
+ * @param {object} state
+ * @param {{ armedAt?: number, countdownSeconds?: number|null }} [options]
+ * @returns {object} state
+ */
+export function armSleep(state, { armedAt = Date.now(), countdownSeconds = null } = {}) {
+  state.sleep = {
+    armed: true,
+    armedAt: isFiniteNumber(armedAt) ? armedAt : Date.now(),
+    countdownSeconds: isFiniteNumber(countdownSeconds) && countdownSeconds >= 0
+      ? Math.trunc(countdownSeconds)
+      : null,
+  };
+  state.updatedAt = state.sleep.armedAt;
+  return state;
+}
+
+/**
+ * Forget the shutdown intent: the machine stays on (or it already went off).
+ *
+ * Mutates `state` in place and returns it.
+ *
+ * @param {object} state
+ * @param {{ now?: number }} [options]
+ * @returns {object} state
+ */
+export function clearSleep(state, { now = Date.now() } = {}) {
+  if (state.sleep === null || state.sleep === undefined) return state;
+  state.sleep = null;
+  state.updatedAt = now;
+  return state;
+}
+
 /**
  * Set the lifecycle phase, ignoring unknown values.
  * Mutates `state` in place and returns it.

package/lib/semver.js

@@ -0,0 +1,49 @@
+/**
+ * dsh-autorestart — the smallest semver comparison this plugin needs.
+ *
+ * The feature announcements are de-duplicated by VERSION, not by equality: a
+ * record counts as "seen" as soon as it is not older than the current feature
+ * version. That comparison has to be numeric — the string comparison of
+ * "0.10.0" and "0.9.0" says the opposite of the truth, because "10" sorts
+ * before "9".
+ *
+ * Only the plain `x.y.z` triple is understood. Anything else (a build
+ * metadata suffix, a pre-release tag, a broken record) has no order at all,
+ * and the caller decides what to do with that.
+ *
+ * @module lib/semver
+ */
+
+/** A version is three numbers and nothing else. */
+const VERSION_PATTERN = /^(\d+)\.(\d+)\.(\d+)$/
+
+/**
+ * Split a version into its three numbers.
+ *
+ * @param {unknown} value
+ * @returns {[number, number, number]|null} null when it is not a version
+ */
+function parseVersion(value) {
+  if (typeof value !== 'string') return null
+  const match = VERSION_PATTERN.exec(value.trim())
+  if (!match) return null
+  return [Number(match[1]), Number(match[2]), Number(match[3])]
+}
+
+/**
+ * Compare two versions numerically.
+ *
+ * @param {unknown} a the left version
+ * @param {unknown} b the right version
+ * @returns {-1|0|1|null} -1 when `a` is older, 1 when it is newer, 0 when they
+ *   are the same, and null when one of them is not a version at all
+ */
+export function compareSemver(a, b) {
+  const left = parseVersion(a)
+  const right = parseVersion(b)
+  if (left === null || right === null) return null
+  for (let index = 0; index < 3; index += 1) {
+    if (left[index] !== right[index]) return left[index] < right[index] ? -1 : 1
+  }
+  return 0
+}

package/lib/sleep.js

@@ -498,6 +498,10 @@ export function runShutdown(plan, {
  *   setInterval?: (fn: () => void, ms: number) => any,
  *   clearInterval?: (handle: any) => void,
  *   titleOf?: (sessionId: string) => string|undefined,
+ *   quietForMs?: () => number,
+ *   graceMs?: () => number,
+ *   restartPending?: () => { pending: boolean, blockers?: any[] },
+ *   onDisarm?: (reason: string) => void,
  *   hostLabel?: string,
  *   supported?: boolean,
  * }} [options]
@@ -512,6 +516,10 @@ export function createSleepController({
   setInterval: setIntervalFn = setInterval,
   clearInterval: clearIntervalFn = clearInterval,
   titleOf = () => '',
+  quietForMs = () => 0,
+  graceMs = () => 0,
+  restartPending = () => ({ pending: false, blockers: [] }),
+  onDisarm = () => {},
   hostLabel = '',
   supported = true,
 } = {}) {
@@ -523,6 +531,9 @@ export function createSleepController({
   let armed = false;
   let blockers = [];
   let remainingMs = 0;
+  // The countdown is over and only the grace window was missing: the machine
+  // goes off when the grace is over, WITHOUT counting down again.
+  let countdownDone = false;
   let lastRun = null;
   let message = supported
     ? '还没点「收工关机」：所有会话收工后倒数几秒，就关掉这台电脑。'
@@ -531,7 +542,46 @@ export function createSleepController({
   let disposed = false;
   let lastTickAt = now();
 
-  /** The busy conversations, as `{ sessionId, title }` entries. */
+  /**
+   * One blocker entry, in the shape the UI expects.
+   *
+   * The Host knows WHAT the blocker is (`kind`: a session or a subagent) and
+   * HOW it is called (`label`: the title of the session, or of the session
+   * that created the subagent). A raw session id never reaches the
+   * interface: an unknown name is a generic one.
+   *
+   * @param {any} entry the entry the Host produced
+   * @param {string} sessionId
+   * @returns {{ sessionId: string, kind: string, label: string|null, name: string, parentTitle: string|null, title: string }}
+   */
+  const blockerEntry = (entry, sessionId) => {
+    const kind = entry.kind === 'subagent' ? 'subagent' : 'session';
+    let label = typeof entry.label === 'string' ? entry.label.trim() : '';
+    if (label === '') {
+      try {
+        const resolved = titleOf(sessionId);
+        label = typeof resolved === 'string' ? resolved.trim() : '';
+      } catch { /* a missing title is not a problem */ }
+    }
+    let name = typeof entry.name === 'string' ? entry.name.trim() : '';
+    // No title, no name: a generic "会话" would only produce a list of
+    // identical entries ("会话、会话、会话"), which says nothing. The client
+    // writes the generic line when the name is empty.
+    if (name === '') name = label;
+    const parentTitle = typeof entry.parentTitle === 'string' ? entry.parentTitle.trim() : '';
+    return {
+      sessionId,
+      kind,
+      label: label !== '' ? label : null,
+      name,
+      parentTitle: parentTitle !== '' ? parentTitle : null,
+      // `title` is the old name of `label`: it stays, so an older client
+      // keeps working.
+      title: label !== '' ? label : name,
+    };
+  };
+
+  /** The busy conversations, as `{ sessionId, kind, label, name }` entries. */
   const listBusy = () => {
     let list = [];
     try {
@@ -546,14 +596,7 @@ export function createSleepController({
       if (!entry || typeof entry !== 'object') continue;
       const sessionId = entry.sessionId == null ? '' : String(entry.sessionId);
       if (sessionId === '') continue;
-      let title = '';
-      try {
-        const resolved = titleOf(sessionId);
-        title = typeof resolved === 'string' ? resolved.trim() : '';
-      } catch { /* a missing title is not a problem */ }
-      // The title falls back to the session id: the field always exists, so
-      // the UI can always say WHO is still working.
-      out.push({ sessionId, title: title !== '' ? title : sessionId });
+      out.push(blockerEntry(entry, sessionId));
     }
     return out;
   };
@@ -570,6 +613,59 @@ export function createSleepController({
     }
   };
 
+  /**
+   * Leave the armed state: the shutdown is over (done, refused or cancelled).
+   *
+   * The Host uses this to forget the recorded intent — the machine stays on
+   * (or it already went off), so the intent must not survive.
+   *
+   * @param {string} reason
+   */
+  const disarm = (reason) => {
+    try { onDisarm(reason); } catch (error) {
+      if (log && typeof log.warn === 'function') log.warn('the disarm hook failed:', errorText(error));
+    }
+  };
+
+  /**
+   * The pending restart, if there is one.
+   *
+   * A restart goes FIRST: the shutdown waits for it — and for the sessions
+   * that resume with it. The intent survives the restart, so the machine goes
+   * off after everything is done, not before.
+   *
+   * @returns {{ pending: boolean, blockers: any[] }}
+   */
+  const readRestartPending = () => {
+    let verdict = null;
+    try { verdict = restartPending(); } catch { verdict = null; }
+    if (!verdict || typeof verdict !== 'object') return { pending: false, blockers: [] };
+    const blockers = Array.isArray(verdict.blockers) ? verdict.blockers : [];
+    return { pending: verdict.pending === true, blockers };
+  };
+
+  /**
+   * The grace window that is still open.
+   *
+   * The plugin only sees the DSH agents. Other plugins (a memory plugin
+   * that writes its notes a few seconds after the conversation ended, a
+   * summary, an MCP callback) queue their work with a timer of their own —
+   * work that is invisible here. The grace window is the extra wait that
+   * leaves them time.
+   *
+   * @returns {{ pending: boolean, remainingMs: number }}
+   */
+  const readGrace = () => {
+    let grace = 0;
+    try { grace = Number(graceMs()); } catch { grace = 0; }
+    if (!Number.isFinite(grace) || grace <= 0) return { pending: false, remainingMs: 0 };
+    let quiet = 0;
+    try { quiet = Number(quietForMs()); } catch { quiet = 0; }
+    if (!Number.isFinite(quiet) || quiet < 0) quiet = 0;
+    const remainingMs = Math.max(0, grace - quiet);
+    return { pending: remainingMs > 0, remainingMs };
+  };
+
   /** The blockers of a gate verdict, in the shape the UI expects. */
   const blockersFromVerdict = (verdict) => {
     const list = verdict && Array.isArray(verdict.blockedBy) ? verdict.blockedBy : [];
@@ -578,18 +674,51 @@ export function createSleepController({
       if (!entry || typeof entry !== 'object') continue;
       const sessionId = entry.sessionId == null ? '' : String(entry.sessionId);
       if (sessionId === '') continue;
-      let title = '';
-      try {
-        const resolved = titleOf(sessionId);
-        title = typeof resolved === 'string' ? resolved.trim() : '';
-      } catch { /* a missing title is not a problem */ }
-      out.push({ sessionId, title: title !== '' ? title : sessionId });
+      out.push(blockerEntry(entry, sessionId));
     }
     return out;
   };
 
-  /** The human name of the busy conversations. */
-  const names = (list) => list.map((entry) => entry.title || entry.sessionId).join('、');
+  /**
+   * The names of the blockers — but only when EVERY one of them has a title.
+   *
+   * A list of generic names ("会话、会话、会话") says nothing and looks like a
+   * bug, so a list with a nameless entry in it is left out entirely: the
+   * caller then writes the line without the parenthetical.
+   *
+   * @param {any[]} list
+   * @returns {string} the joined names, or '' when the list cannot be named
+   */
+  const names = (list) => {
+    const out = [];
+    for (const entry of Array.isArray(list) ? list : []) {
+      const label = entry && typeof entry.label === 'string' ? entry.label.trim() : '';
+      const name = entry && typeof entry.name === 'string' ? entry.name.trim() : '';
+      if (label === '' || name === '') return '';
+      out.push(name);
+    }
+    return out.join('、');
+  };
+
+  /**
+   * The line that says WHO the machine waits for.
+   *
+   * - every blocker has a title → the names are listed;
+   * - one blocker with a title → the singular form ("等「甲」收工");
+   * - otherwise → the plain count, without a parenthetical.
+   *
+   * @param {any[]} list the blockers
+   * @param {{ immediate?: boolean }} options `immediate` = no countdown at all
+   * @returns {string}
+   */
+  const waitingFor = (list, { immediate = false } = {}) => {
+    const count = Array.isArray(list) ? list.length : 0;
+    const tail = immediate ? '收工后立即关机。' : '收工后开始倒数。';
+    const named = names(list);
+    if (count === 1 && named !== '') return `等「${named}」收工，${tail}`;
+    if (count > 0 && named !== '') return `等 ${count} 个任务收工（${named}），${tail}`;
+    return `等 ${count} 个任务收工，${tail}`;
+  };
 
   /** Normalize whatever the shutdown handler returned into the reported shape. */
   const normalizeRun = (value) => {
@@ -652,24 +781,61 @@ export function createSleepController({
     if (!armed) return status();
     if (phase === 'shutting-down') return status();
     try {
+      // A pending restart goes FIRST. The shutdown waits for it — and for the
+      // sessions that resume with it. The intent survives the restart, so the
+      // machine goes off after everything is done.
+      const pendingRestart = readRestartPending();
+      if (pendingRestart.pending) {
+        phase = 'waiting';
+        blockers = pendingRestart.blockers;
+        countdownDone = false;
+        remainingMs = countdownMs;
+        message = '等这次重启完成后再关机……';
+        return status();
+      }
+
       const busy = listBusy();
       if (busy.length > 0) {
         const again = phase === 'countdown';
         phase = 'waiting';
         blockers = busy;
+        countdownDone = false;
         remainingMs = countdownMs;
         message = again
-          ? `${names(busy)} 又开始干活了，倒数先停一下，等它们收工。`
-          : (countdownMs > 0
-            ? `等 ${busy.length} 个会话收工（${names(busy)}），收工后开始倒数。`
-            : `等 ${busy.length} 个会话收工（${names(busy)}），收工后立即关机。`);
+          ? (names(busy) !== ''
+            ? `${names(busy)} 又开始干活了，倒数先停一下，等它们收工。`
+            : '又有任务开始干活了，倒数先停一下，等它们收工。')
+          : waitingFor(busy, { immediate: countdownMs === 0 });
+        return status();
+      }
+
+      // The grace window: the last conversation finished a moment ago, and
+      // other plugins still have work queued that this plugin cannot see (a
+      // memory plugin writing its notes, a summary). The countdown does not
+      // start before the grace is over — so the grace never pushes the
+      // countdown back, it only delays its start.
+      const grace = readGrace();
+      if (grace.pending) {
+        phase = 'waiting';
+        blockers = [];
+        remainingMs = countdownMs;
+        message = `再等 ${Math.ceil(grace.remainingMs / 1000)} 秒，给记忆/总结类插件留点时间……`;
         return status();
       }
 
       if (phase !== 'countdown') {
         phase = 'countdown';
-        remainingMs = countdownMs;
-        lastTickAt = now();
+        // The countdown runs: nobody blocks it any more.
+        blockers = [];
+        if (countdownDone) {
+          // The countdown is over and only the grace window was missing: the
+          // countdown does NOT start again, the machine goes off as soon as
+          // the grace is over (the gate below decides).
+          remainingMs = 0;
+        } else {
+          remainingMs = countdownMs;
+          lastTickAt = now();
+        }
       } else {
         const stamp = now();
         const elapsed = Math.max(TICK_MS, stamp - lastTickAt);
@@ -689,16 +855,25 @@ export function createSleepController({
       if (verdict.allow !== true) {
         phase = 'waiting';
         blockers = blockersFromVerdict(verdict);
-        remainingMs = countdownMs;
         const reason = typeof verdict.reason === 'string' ? verdict.reason : '';
-        if (reason === 'settling') {
-          // The machine was not quiet long enough: say THAT, and do not claim
-          // that somebody started working.
-          message = '机器还没安静够久，再等一轮……';
-        } else if (blockers.length > 0) {
-          message = `倒数结束前又有人开始干活了（${names(blockers)}），关机先暂停，等所有会话收工。`;
+        if (reason === 'grace') {
+          // Only the grace window was missing: the countdown is over and
+          // stays over — the machine goes off when the grace is over.
+          countdownDone = true;
+          remainingMs = 0;
+          message = '最后一点收尾还没结束，再给记忆/总结类插件留几秒……';
         } else {
-          message = '倒数结束时机器还没安静下来，关机先暂停，再等一轮。';
+          countdownDone = false;
+          remainingMs = countdownMs;
+          if (reason === 'settling') {
+            // The machine was not quiet long enough: say THAT, and do not claim
+            // that somebody started working.
+            message = '机器还没安静够久，再等一轮……';
+          } else if (blockers.length > 0) {
+            message = `倒数结束前又有人开始干活了${names(blockers) !== '' ? `（${names(blockers)}）` : ''}，关机先暂停，等所有会话收工。`;
+          } else {
+            message = '倒数结束时机器还没安静下来，关机先暂停，再等一轮。';
+          }
         }
         return status();
       }
@@ -737,9 +912,14 @@ export function createSleepController({
           remainingMs = 0;
           const planned = [run.command || '', ...run.args].filter((part) => part !== '').join(' ');
           message = `试运行：本来会执行 ${planned}，这次不会真的关机。`;
+          disarm('dry-run');
+          return;
+        }
+        if (run.executed === true) {
+          // The machine is going off: the intent is spent.
+          disarm('shutdown-completed');
           return;
         }
-        if (run.executed === true) return;
         if (run.error === 'gate-blocked') {
           // Somebody started working in the very last moment: wait for them —
           // and KEEP the list, so the waiting card can say WHO is still busy.
@@ -753,7 +933,7 @@ export function createSleepController({
             // that somebody started working.
             message = '机器还没安静够久，再等一轮……';
           } else if (blockers.length > 0) {
-            message = `倒数结束时又有人开始干活了（${names(blockers)}），关机先暂停，等所有会话收工。`;
+            message = `倒数结束时又有人开始干活了${names(blockers) !== '' ? `（${names(blockers)}）` : ''}，关机先暂停，等所有会话收工。`;
           } else {
             message = '倒数结束时机器还没安静下来，关机先暂停，再等一轮。';
           }
@@ -765,6 +945,7 @@ export function createSleepController({
         blockers = [];
         remainingMs = 0;
         message = `关机命令没跑起来（${run.error || 'unknown error'}），电脑还开着，可以再点一次月亮按钮。`;
+        disarm('shutdown-failed');
       };
       if (result && typeof result.then === 'function') {
         result.then(
@@ -796,6 +977,7 @@ export function createSleepController({
     armed = true;
     phase = 'waiting';
     blockers = [];
+    countdownDone = false;
     remainingMs = countdownMs;
     lastTickAt = now();
     message = countdownMs > 0
@@ -812,8 +994,10 @@ export function createSleepController({
     armed = false;
     phase = 'cancelled';
     blockers = [];
+    countdownDone = false;
     remainingMs = 0;
     message = '收工关机已取消，电脑不会关机。';
+    disarm('cancelled');
     return status();
   };
 

package/locale/en.json

@@ -24,6 +24,12 @@
       "value": "{n} seconds",
       "hint": "After the button: wait for every conversation to be done, count down this many seconds and switch off. \"No countdown\" switches off as soon as the conversations are done."
     },
+    "grace": {
+      "label": "Wait a few more seconds after the work is done",
+      "immediate": "Do not wait (restart/switch off right away)",
+      "value": "{n} seconds",
+      "hint": "After the last conversation finished, wait this long before the host is really restarted or switched off — this plugin only sees the DSH conversations, not the work other plugins queue with a timer. If a conversation starts working again while waiting, the timer starts over."
+    },
     "backup": {
       "label": "Backup before a restart",
       "hint": "Take a snapshot of the current configuration before every restart, so a host that cannot boot again is rolled back automatically."
@@ -81,7 +87,8 @@
     "waiting": {
       "title": "Waiting for everyone to finish",
       "body": "Once these sessions are done, the machine powers off:",
-      "count": "{n} session(s) still working",
+      "count": "{n} task(s) still working",
+      "subagents": "{k} of them are subagents",
       "blocker": "· {title}",
       "none": "(checking who is still busy)",
       "cancel": "Keep it on"

package/locale/zh.json

@@ -24,6 +24,12 @@
       "value": "{n} 秒",
       "hint": "按下按钮后，等所有会话收工，再倒数这么多秒才关机；「不倒数」表示会话一收工就关机。"
     },
+    "grace": {
+      "label": "收工后再等几秒（给记忆/总结类插件留时间）",
+      "immediate": "不等（立即重启/关机）",
+      "value": "{n} 秒",
+      "hint": "最后一个会话收工后，再等这么久才真正重启或关机——我们只看得见 DSH 的会话，看不见别的插件用定时器排队的活。等待期间如果又有会话开始干活，会重新计时。"
+    },
     "backup": {
       "label": "重启前备份",
       "hint": "每次重启前先快照一次当前配置；万一重启后起不来，能自动回退。"
@@ -81,7 +87,8 @@
     "waiting": {
       "title": "还在等大家收工",
       "body": "等这些会话忙完，就轮到关机啦：",
-      "count": "还有 {n} 个会话在干活",
+      "count": "还有 {n} 个任务在干活",
+      "subagents": "其中 {k} 个是子智能体",
       "blocker": "· {title}",
       "none": "（正在确认还有谁在忙）",
       "cancel": "不关了"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-autorestart",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "type": "module",
   "description": "DeepSeek Harness plugin: restart without losing work. Waits until every conversation is idle, restarts the host, then automatically resumes the interrupted sessions. AI-generated, not human-reviewed: use with caution.",
   "license": "MIT",