dsh-autorestart 0.6.1 → 0.6.2

package/index.js

@@ -76,6 +76,12 @@ import {
   scheduleDetachedRestart,
 } from './lib/restart.js'
 import { compareSemver } from './lib/semver.js'
+import { isWorkSessionEvent } from './lib/activity.js'
+import {
+  createQueuedTracker,
+  DEFAULT_QUEUED_GRACE_MS,
+  normalizeQueuedGraceMs,
+} from './lib/queued.js'
 import {
   createSleepController,
   COUNTDOWN_CHOICES,
@@ -87,34 +93,52 @@ import {
 } from './lib/sleep.js'
 
 /**
- * The grace window: how long the host waits after the LAST conversation
- * finished before it is really restarted or switched off.
+ * The RESTART reserve: how long the host waits after the LAST conversation
+ * finished before it is really restarted.
  *
  * This plugin can only see 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. A short, configurable grace window is left for it.
+ * invisible here. A short, configurable reserve window is left for it.
+ *
+ * The reserve belongs to the RESTART only: a restart is a daily operation, so
+ * it should happen as soon as the conversations are done. Default: none.
+ *
+ * The graceful shutdown has NO reserve of its own: it has a VISIBLE countdown
+ * (`sleepCountdownSeconds`), and that countdown IS the wait before the
+ * machine goes off. A second, invisible window next to it would only say the
+ * same thing twice — so there is none.
  *
  * The values are the ones the settings page offers (in milliseconds).
  */
-const GRACE_CHOICES_MS = Object.freeze([0, 3000, 5000, 10000, 20000, 30000])
+const GRACE_CHOICES_MS = Object.freeze([0, 5000, 10000, 20000, 30000, 60000])
 
-/** The grace window that is used when nothing was configured. */
-const DEFAULT_GRACE_MS = 10000
+/** The RESTART reserve that is used when nothing was configured. */
+const DEFAULT_RESTART_GRACE_MS = 0
 
 /**
- * Snap a grace value onto the nearest offered choice.
+ * How often the "the restart is waiting for a long time" line may be logged.
+ *
+ * The restart gate polls every few seconds, so an unthrottled line would
+ * flood the log with the same sentence. Once a minute is enough to say that
+ * the wait is still going on.
+ */
+const LONG_WAIT_LOG_INTERVAL_MS = 60000
+
+/**
+ * Snap a reserve value onto the nearest offered choice.
  *
  * A profile that carries a value that is not offered (a hand-edited row, an
  * older build) must not break the boot: the value is snapped onto the
  * nearest choice, exactly like the countdown length is.
  *
  * @param {unknown} value
+ * @param {number} [fallback] the value used when the input is not a number
  * @returns {number} one of {@link GRACE_CHOICES_MS}
  */
-function snapGraceChoice(value) {
+function snapGraceChoice(value, fallback = DEFAULT_RESTART_GRACE_MS) {
   const raw = Number(value)
-  if (!Number.isFinite(raw) || raw < 0) return DEFAULT_GRACE_MS
+  if (!Number.isFinite(raw) || raw < 0) return fallback
   let best = GRACE_CHOICES_MS[0]
   let bestDistance = Math.abs(raw - best)
   for (const choice of GRACE_CHOICES_MS) {
@@ -134,7 +158,7 @@ function snapGraceChoice(value) {
  * `pluginVersion()`), but a bundled installation may not ship that file — so
  * the constant below is the last resort. A test keeps the two in sync.
  */
-const PLUGIN_VERSION_FALLBACK = '0.6.1'
+const PLUGIN_VERSION_FALLBACK = '0.6.2'
 
 /**
  * The version of the graceful-shutdown FEATURE, not the version of the package.
@@ -380,8 +404,19 @@ function buildConfigSchema() {
       // Other plugins queue work with timers of their own (a memory plugin
       // writing its notes, a summary, an MCP callback) and that work is
       // invisible here — so a short, configurable grace window is left for it.
-      restartGraceMs: schemastery.number().min(0).default(DEFAULT_GRACE_MS)
-        .description('Milliseconds to wait after the last conversation finished before the host is really restarted or switched off: the grace window for work other plugins queue with a timer (0 / 3 / 5 / 10 / 20 / 30 seconds, default 10).'),
+      // The RESTART reserve: the extra wait after the last conversation
+      // finished, before the host is really restarted. A restart is a daily
+      // operation, so the default is none (0 / 5 / 10 / 20 / 30 / 60 seconds).
+      restartGraceMs: schemastery.number().min(0).default(DEFAULT_RESTART_GRACE_MS)
+        .description('Milliseconds to wait after the last conversation finished before the host is really RESTARTED: the reserve for work other plugins queue with a timer (0 / 5 / 10 / 20 / 30 / 60 seconds, default 0 = no extra wait).'),
+      // The graceful shutdown has no reserve of its own: the visible countdown
+      // (sleepCountdownSeconds) IS the wait before the machine goes off.
+      // The upper bound of a QUEUED inbox message: a message that nobody
+      // claims within this window is stuck, and it stops blocking the restart.
+      // Without it a single unclaimed message kept the restart pending for
+      // ever (the "the restart never happens" defect).
+      queuedGraceMs: schemastery.number().min(0).default(DEFAULT_QUEUED_GRACE_MS)
+        .description('Milliseconds an unclaimed (queued) inbox message may block the restart: a message that is still unclaimed after this window is treated as stuck and no longer blocks the restart (0 = no upper bound, the old behaviour; default 60000).'),
       autoReloadPage: schemastery.boolean().default(true)
         .description('Reload the web page automatically when the host boot token changes.'),
       blockManualRestart: schemastery.boolean().default(true)
@@ -448,7 +483,11 @@ const DEFAULTS = {
   restartCommand: '',
   relaunchDelaySeconds: 2,
   settleMs: 2000,
-  restartGraceMs: DEFAULT_GRACE_MS,
+  restartGraceMs: DEFAULT_RESTART_GRACE_MS,
+  // The upper bound of a queued (unclaimed) inbox message: after this time it
+  // is treated as stuck and stops blocking the restart. 0 switches the
+  // protection off (the old behaviour: a queued message blocks for ever).
+  queuedGraceMs: DEFAULT_QUEUED_GRACE_MS,
   autoReloadPage: true,
   blockManualRestart: true,
   healthPath: '/__dsh_autorestart/health',
@@ -495,9 +534,12 @@ function normalizeConfig(raw) {
   // profile that still carries an old value (15, 45, …) is snapped onto the
   // nearest one instead of breaking, and 0 means "no countdown at all".
   config.sleepCountdownSeconds = snapCountdownChoice(config.sleepCountdownSeconds)
-  // The grace window is one of the offered choices as well: a hand-edited
+  // The restart reserve is one of the offered choices as well: a hand-edited
   // profile value is snapped onto the nearest one instead of breaking.
-  config.restartGraceMs = snapGraceChoice(config.restartGraceMs)
+  config.restartGraceMs = snapGraceChoice(config.restartGraceMs, DEFAULT_RESTART_GRACE_MS)
+  // The upper bound of a queued message is a plain number: a wrong or negative
+  // value falls back to the default, and 0 switches the protection off.
+  config.queuedGraceMs = normalizeQueuedGraceMs(config.queuedGraceMs)
   if (typeof config.sleepCommand !== 'string') config.sleepCommand = ''
   if (typeof config.showSleepButton !== 'boolean') config.showSleepButton = true
   return config
@@ -1233,7 +1275,43 @@ export function createRuntime(ctx, config, options = {}) {
   /** When the last conversation activity was observed; the settle window starts here. */
   let lastActivityAt = Date.now()
 
-  /** Record conversation activity (any agent turn, session event or queued message). */
+  /**
+   * When a busy conversation was seen for the last time.
+   *
+   * The quiet window measures the time since the last REAL work: a running
+   * turn or a queued message. The host polls the agent list every few
+   * seconds, so this marker follows the work exactly — and it is NOT reset by
+   * the routine session events the interface produces while it synchronises
+   * (those used to reset the window every 2-3 seconds, so a window longer
+   * than that interval could never fill and the restart never fired).
+   */
+  let lastBusyAt = 0
+
+  /**
+   * When the "the restart is waiting for a long time" line was logged last.
+   *
+   * The gate polls every few seconds, so the line is rate limited: at most one
+   * per minute for the SAME restart request. A new request (`requestedAt`
+   * changed) logs right away.
+   */
+  let longWaitLog = { at: 0, requestedAt: 0 }
+
+  /**
+   * When the diagnostic line of the restart gate was logged last.
+   *
+   * The gate is evaluated every few seconds, so the line is rate limited to
+   * once a minute: it says what the gate decided and why, which is the first
+   * thing to look at when "the restart never happens" is reported.
+   */
+  let lastDecisionLogAt = 0
+
+  /**
+   * Record REAL conversation activity (an agent turn that started or ended, a
+   * message that was queued, a session event that says work happened).
+   *
+   * The routine session events of the interface do NOT go through here: they
+   * would keep the quiet window from ever filling.
+   */
   const noteActivity = () => {
     lastActivityAt = Date.now()
   }
@@ -1253,6 +1331,53 @@ export function createRuntime(ctx, config, options = {}) {
     return count
   }
 
+  /**
+   * A short human-readable duration for the log ("45s", "2m 5s", "1h 3m").
+   *
+   * @param {number} ms
+   * @returns {string}
+   */
+  const describeWait = (ms) => {
+    const total = Math.max(0, Math.round(Number(ms) || 0))
+    const seconds = Math.floor(total / 1000)
+    if (seconds < 60) return `${seconds}s`
+    const minutes = Math.floor(seconds / 60)
+    if (minutes < 60) {
+      const rest = seconds % 60
+      return rest === 0 ? `${minutes}m` : `${minutes}m ${rest}s`
+    }
+    const hours = Math.floor(minutes / 60)
+    const restMinutes = minutes % 60
+    return restMinutes === 0 ? `${hours}h` : `${hours}h ${restMinutes}m`
+  }
+
+  /**
+   * The readable names of the sessions that hold the restart.
+   *
+   * A session without a title falls back to its id: the log has to say WHO
+   * holds the restart, and an empty name would say nothing.
+   *
+   * @param {any[]} blockedBy
+   * @returns {string}
+   */
+  const describeBlockers = (blockedBy) => {
+    const list = Array.isArray(blockedBy) ? blockedBy : []
+    const names = []
+    for (const entry of list) {
+      if (!entry || typeof entry !== 'object') continue
+      const name = typeof entry.name === 'string' && entry.name.trim() !== ''
+        ? entry.name.trim()
+        : (typeof entry.label === 'string' && entry.label.trim() !== ''
+          ? entry.label.trim()
+          : String(entry.sessionId || ''))
+      if (name === '') continue
+      names.push(name)
+    }
+    if (names.length === 0) return 'another conversation'
+    if (names.length === 1) return names[0]
+    return names.join(', ')
+  }
+
   /**
    * Whether this agent is a subagent (a delegated child), and which session
    * created it.
@@ -1329,10 +1454,28 @@ export function createRuntime(ctx, config, options = {}) {
     }
   }
 
+  /**
+   * The tracker of the QUEUED messages.
+   *
+   * It remembers for how long a session has had an unclaimed inbox message, so
+   * a message that nobody claims stops blocking the restart instead of
+   * blocking it for ever. A session that is RUNNING is never judged here: a
+   * live turn always blocks, under every grace setting.
+   */
+  const queuedTracker = createQueuedTracker()
+
+  /** The sessions the tracker saw in the last round (for the cleanup). */
+  const queuedSessions = new Set()
+
   /**
    * Every conversation that is still working, subagents and teammates included.
    * 'running' is a live turn; 'queued' is inbox work that has not started yet.
    *
+   * A queued message only blocks the restart until the grace window
+   * (`queuedGraceMs`) is over: after that it is stuck — nobody will ever claim
+   * it — so it stops blocking the restart and is named in the log. A running
+   * conversation ALWAYS blocks.
+   *
    * Every entry carries the kind of the blocker and a readable name, so the
    * interface can tell a session from a subagent and never has to show a raw
    * session id.
@@ -1345,15 +1488,52 @@ export function createRuntime(ctx, config, options = {}) {
     } catch {
       agents = []
     }
+    const seen = new Set()
     for (const agent of agents) {
       try {
         if (!agent || !agent.id) continue
         const sessionId = String(agent.id)
+        seen.add(sessionId)
         const described = describeBlocker(sessionId, agent)
-        if (agent.status === 'running') out.push({ sessionId, reason: 'running', ...described })
-        else if (pendingInboxCount(agent) > 0) out.push({ sessionId, reason: 'queued', ...described })
+        if (agent.status === 'running') {
+          // A live turn ALWAYS blocks the restart — under every grace
+          // setting. The queued timer of that session is dropped: the work is
+          // being done, so it is not a stuck queue.
+          queuedTracker.forget(sessionId)
+          out.push({ sessionId, reason: 'running', ...described })
+        } else if (pendingInboxCount(agent) > 0) {
+          const observed = queuedTracker.observe(sessionId, true, config.queuedGraceMs)
+          if (observed.becameStale) {
+            // The message has been waiting longer than the grace window and
+            // nobody claimed it: it is stuck. The session is named here, so
+            // the user can see WHICH conversation holds the queue.
+            log.warn(
+              `the queued message of session ${sessionId} has been waiting ${describeWait(observed.ageMs)} and nobody claimed it; it no longer blocks the restart`,
+              {
+                sessionId,
+                ageMs: observed.ageMs,
+                queuedGraceMs: config.queuedGraceMs,
+              },
+            )
+          }
+          if (observed.blocking) out.push({ sessionId, reason: 'queued', ...described })
+        } else {
+          // No queued work any more: the timer of that session is dropped, so
+          // a NEW queue starts counting from zero.
+          queuedTracker.observe(sessionId, false, config.queuedGraceMs)
+        }
       } catch {}
     }
+    // A session that is gone (closed) drops its record as well.
+    for (const sessionId of queuedSessions) {
+      if (!seen.has(sessionId)) queuedTracker.forget(sessionId)
+    }
+    queuedSessions.clear()
+    for (const sessionId of seen) queuedSessions.add(sessionId)
+    // Real work is still going on: the quiet window starts over. This is the
+    // marker that makes the quiet window measure "since the last real work"
+    // instead of "since the last session event of any kind".
+    if (out.length > 0) lastBusyAt = Date.now()
     return out
   }
 
@@ -1695,13 +1875,33 @@ export function createRuntime(ctx, config, options = {}) {
    */
   const pendingRestart = () => state.restart !== null && state.restart !== undefined
 
-  /** How long the host has been quiet (no conversation activity at all). */
-  const quietForMs = () => Math.max(0, Date.now() - lastActivityAt)
+  /**
+   * The moment the quiet window started.
+   *
+   * It is the LATER of the two markers:
+   *   - `lastActivityAt`: the last real activity signal (a turn that started
+   *     or ended, a message that was queued);
+   *   - `lastBusyAt`: the last moment a conversation was seen working (a
+   *     running turn or a queued message).
+   *
+   * The routine session events of the interface (a title, a projection, a
+   * context request) are NOT activity: they arrive every two to three
+   * seconds, so counting them would keep the quiet window from ever filling
+   * — and the restart would never fire.
+   *
+   * @returns {number} a timestamp in milliseconds
+   */
+  const quietSince = () => Math.max(lastActivityAt, lastBusyAt)
+
+  /** How long the host has been quiet (no real conversation activity at all). */
+  const quietForMs = () => Math.max(0, Date.now() - quietSince())
 
   /**
-   * The grace window: how much longer the host waits after the last
-   * conversation finished, so that work other plugins queue with a timer (a
-   * memory plugin writing its notes, a summary) still gets its chance.
+   * The RESTART reserve: how much longer the host waits after the last
+   * conversation finished before it is really restarted.
+   *
+   * A restart is a daily operation, so the default is none: the host restarts
+   * as soon as the conversations are done and the settle window has passed.
    */
   const graceMs = () => config.restartGraceMs
 
@@ -1716,11 +1916,45 @@ export function createRuntime(ctx, config, options = {}) {
   /** The two-layer restart gate: no busy conversation AND a quiet window. */
   const gate = () => restartGate(state, {
     busyAgents: busyAgents(),
-    lastActivityAt,
+    lastActivityAt: quietSince(),
     now: Date.now(),
     settleMs: effectiveSettleMs(),
   })
 
+  /**
+   * The description of a LONG wait, or null when the restart is not waiting
+   * for the long time yet.
+   *
+   * A pending restart that passed the hard deadline while a conversation was
+   * still running is not "just a little longer": it is a long wait, and the
+   * user has to SEE it — how long it has been waiting, why, and who holds it.
+   * The request itself is never dropped: the restart stays pending and fires
+   * as soon as the gate is quiet again.
+   *
+   * @param {number} [now]
+   * @returns {{ since: number, reason: string, waitedMs: number, blockedBy: any[] }|null}
+   */
+  const longWaitInfo = (now = Date.now()) => {
+    const restart = state.restart
+    if (!restart || typeof restart !== 'object') return null
+    const requestedAt = Number.isFinite(restart.requestedAt) ? restart.requestedAt : 0
+    if (requestedAt <= 0) return null
+    const hardMs = Number.isFinite(config.deferHardMs) ? config.deferHardMs : 0
+    // The long wait begins when the hard deadline is reached.
+    const since = requestedAt + hardMs
+    if (now < since) return null
+    const verdict = gate()
+    if (verdict.allow) return null
+    const blockedBy = goalAwareBlockingDetails(runtime, verdict.blockedBy)
+    if (blockedBy.length === 0) return null
+    return {
+      since,
+      reason: 'hard-deadline-waiting-for-conversations',
+      waitedMs: Math.max(0, now - requestedAt),
+      blockedBy,
+    }
+  }
+
   /**
    * Cached session titles, used to label the blocking sessions in the
    * client's "pending restart" details panel.
@@ -2073,7 +2307,7 @@ const titleOfSummary = (item) => {
     const decision = restartDecision(state, {
       anyAgentRunning: busy.length > 0,
       busyAgents: busy,
-      lastActivityAt,
+      lastActivityAt: quietSince(),
       settleMs: effectiveSettleMs(),
       now,
       softMs: config.deferSoftMs,
@@ -2082,6 +2316,23 @@ const titleOfSummary = (item) => {
       forceRestartWhenBusy: config.forceRestartWhenBusy,
     })
     if (decision.log) log.info(decision.log)
+    // The diagnostic line of the pending restart: what the gate decided and
+    // why. It is rate limited (once a minute) so the 3s poll does not flood
+    // the log, and it is the first thing to look at when "the restart never
+    // happens" is reported.
+    if (now - lastDecisionLogAt >= LONG_WAIT_LOG_INTERVAL_MS) {
+      lastDecisionLogAt = now
+      log.info(
+        `restart gate: action=${decision.action} reason=${decision.reason} busyCount=${busy.length} quietForMs=${Math.max(0, now - quietSince())} effectiveSettleMs=${effectiveSettleMs()}`,
+        {
+          action: decision.action,
+          reason: decision.reason,
+          busyCount: busy.length,
+          quietForMs: Math.max(0, now - quietSince()),
+          effectiveSettleMs: effectiveSettleMs(),
+        },
+      )
+    }
     switch (decision.action) {
       case 'wait':
         return
@@ -2092,6 +2343,28 @@ const titleOfSummary = (item) => {
         }
         return
       }
+      case 'long-wait': {
+        // The hard deadline is over and a conversation still holds the
+        // restart. The request is KEPT — the user asked for a restart, it must
+        // never be dropped silently — and the wait becomes VISIBLE: a clear
+        // log line (rate limited, so the 3s poll does not flood the log) and
+        // the `longWait` block of the state payload.
+        const requestedAt = Number.isFinite(state.restart.requestedAt) ? state.restart.requestedAt : now
+        const waitedMs = Math.max(0, now - requestedAt)
+        const lastAt = longWaitLog.requestedAt === requestedAt ? longWaitLog.at : 0
+        if (now - lastAt >= LONG_WAIT_LOG_INTERVAL_MS) {
+          longWaitLog = { at: now, requestedAt }
+          log.warn(
+            `the restart has been waiting for ${describeWait(waitedMs)}; ${describeBlockers(decision.blockedBy)} still holds it — cancel the restart or wait for that work to finish`,
+            {
+              waitedMs,
+              blockedBy: decision.blockedBy,
+              reason: decision.reason,
+            },
+          )
+        }
+        return
+      }
       case 'restart':
       case 'force-restart': {
         void executeRestart()
@@ -2351,13 +2624,23 @@ const titleOfSummary = (item) => {
      */
     pendingRestart,
     /**
-     * How long the host has been quiet (no conversation activity at all).
+     * How long the host has been quiet (no REAL conversation activity: a
+     * running turn, a queued message, a turn that started or ended).
+     *
+     * The routine session events of the interface do not count.
      *
      * @returns {number}
      */
     quietForMs,
     /**
-     * The grace window: the extra wait after the last conversation finished.
+     * The moment the quiet window started.
+     *
+     * @returns {number} a timestamp in milliseconds
+     */
+    quietSince,
+    /**
+     * The RESTART reserve: the extra wait after the last conversation
+     * finished, before the host is really restarted.
      *
      * @returns {number} milliseconds
      */
@@ -2378,6 +2661,19 @@ const titleOfSummary = (item) => {
     noteActivity,
     busyAgents,
     gate,
+    /**
+     * The description of a long wait (null when there is none).
+     *
+     * @param {number} [now]
+     * @returns {{ since: number, reason: string, waitedMs: number, blockedBy: any[] }|null}
+     */
+    longWaitInfo,
+    /**
+     * The upper bound of a queued (unclaimed) inbox message.
+     *
+     * @returns {number} milliseconds
+     */
+    queuedGraceMs: () => config.queuedGraceMs,
     sessionTitle,
     disarmGoal,
     disarmBlockingGoals,
@@ -3107,6 +3403,7 @@ function registerTools(ctx, runtime, config) {
           quietForMs: { type: 'number' },
           graceMs: { type: 'number' },
           effectiveSettleMs: { type: 'number' },
+          queuedGraceMs: { type: 'number' },
           blockedBy: {
             type: 'array',
             items: {
@@ -3158,10 +3455,12 @@ function registerTools(ctx, runtime, config) {
         pendingRestart: state.restart !== null,
         gateAllow: verdict.allow,
         quietForMs: Math.round(verdict.quietForMs),
-        // The grace window (the extra wait after the last conversation
+        // The RESTART reserve (the extra wait after the last conversation
         // finished) and the quiet window the gate really uses.
         graceMs: runtime.graceMs(),
         effectiveSettleMs: runtime.effectiveSettleMs(),
+        // The upper bound of a queued (unclaimed) inbox message.
+        queuedGraceMs: runtime.queuedGraceMs(),
         blockedBy: blockingDetails(verdict.blockedBy),
         parkedGoals: parkedGoalDetails(),
         recovery: recoveryList(state),
@@ -3417,7 +3716,7 @@ function injectPageHeartbeat(html, bootId, routePath) {
 const AUTORESTART_PROMPT = [
   '## Restart policy (dsh-autorestart)',
   '- When DeepSeek Harness itself must restart (for example to load an installed or updated plugin bundle), do NOT kill or relaunch the app yourself with pwsh/taskkill/Stop-Process/npm scripts. A hard guard blocks such commands anyway (denials mention `blockManualRestart`).',
-  '- Call the `continuum_restart` tool instead (optional arguments: `reason`, `resume`, `defer_seconds`, `parkGoals`). It waits until every conversation is idle (no running turn, no queued inbox work) AND the host has been quiet for `settleMs` (default 2000 ms); the detached helper re-checks that gate immediately before killing, so other conversations are never killed mid-turn. It then relaunches the app, and after boot this plugin resumes the session and continues the work automatically.',
+  '- Call the `continuum_restart` tool instead (optional arguments: `reason`, `resume`, `defer_seconds`, `parkGoals`). It waits until every conversation is idle (no running turn — a running turn ALWAYS blocks; an inbox message nobody claimed blocks only until `queuedGraceMs`, default 60000 ms, after which it is treated as stuck and no longer blocks) AND the host has been quiet for `settleMs` (default 2000 ms); the detached helper re-checks that gate immediately before killing, so other conversations are never killed mid-turn. It then relaunches the app, and after boot this plugin resumes the session and continues the work automatically.',
   '- A goal-driven session is DISARMED automatically before the restart (its current round still finishes, nothing is lost), because such a session would otherwise keep the restart waiting forever: disarming only removes the process-local continuation authority, so no new round starts and the session goes idle. After the restart the goal is re-armed and continues. A goal whose round budget is spent cannot be continued and is reported instead. You can disarm your own goal on demand with `continuum_park_goal`, and retry a stuck recovery with `continuum_recover_now`.',
   '- Persist anything the next turn needs before restarting (workspace files, `todo_write`, goal state); do not rely on in-memory state.',
   '- Inspect the lifecycle with `continuum_status`; cancel a pending restart with `continuum_cancel_restart`.',
@@ -4019,7 +4318,7 @@ function buildChoiceRoute(ctx, runtime, config) {
           res.end(JSON.stringify({
             ok: false,
             error: 'no-choice',
-            instruction: 'Send { "includePlugins": true | false } and/or { "backupIncludePlugins": true | false } and/or { "backupOnRestart": true | false } and/or { "showSleepButton": true | false } and/or { "sleepCountdownSeconds": 0 | 10 | 20 | 30 | 60 } and/or { "restartGraceMs": 0 | 3000 | 5000 | 10000 | 20000 | 30000 }.',
+            instruction: 'Send { "includePlugins": true | false } and/or { "backupIncludePlugins": true | false } and/or { "backupOnRestart": true | false } and/or { "showSleepButton": true | false } and/or { "sleepCountdownSeconds": 0 | 10 | 20 | 30 | 60 } and/or { "restartGraceMs": 0 | 5000 | 10000 | 20000 | 30000 | 60000 }.',
           }))
           return
         }
@@ -4158,16 +4457,16 @@ function sleepDryRun() {
  * happened). The sleep feature counts down on screen itself, so it only needs
  * the busy check — and it keeps `settleMs` out of the picture entirely.
  *
- * The GRACE window is the exception: it is not a settle window but the extra
- * wait for work this plugin cannot see (a memory plugin writing its notes a
- * few seconds after the conversation ended). It is honoured BEFORE the
- * countdown starts, so the countdown is never pushed back by it.
+ * The shutdown has NO invisible reserve of its own: the visible countdown
+ * (`sleepCountdownSeconds`) IS the wait before the machine goes off, and it is
+ * on screen, so the user can see it and cancel it. A second, hidden window
+ * next to it would only say the same thing twice.
  *
  * The restart gate itself is untouched: the restart feature keeps its quiet
- * window exactly as it was (plus the same grace).
+ * window exactly as it was (plus its own restart reserve).
  *
  * @param {object} runtime
- * @returns {{ allow: boolean, reason: 'busy'|'grace'|'quiet', blockedBy: any[] }}
+ * @returns {{ allow: boolean, reason: 'busy'|'quiet', blockedBy: any[] }}
  */
 function sleepGate(runtime) {
   // A pending restart goes FIRST: the shutdown waits for it — and for the
@@ -4199,16 +4498,8 @@ function sleepGate(runtime) {
   }
   const list = Array.isArray(busy) ? busy : []
   if (list.length > 0) return { allow: false, reason: 'busy', blockedBy: list }
-  // The grace window: the last conversation may have finished a moment ago,
-  // and other plugins still have work queued that this plugin cannot see.
-  let quiet = 0
-  let grace = 0
-  try { quiet = Number(runtime.quietForMs()) } catch { quiet = 0 }
-  try { grace = Number(runtime.graceMs()) } catch { grace = 0 }
-  if (!Number.isFinite(quiet) || quiet < 0) quiet = 0
-  if (Number.isFinite(grace) && grace > 0 && quiet < grace) {
-    return { allow: false, reason: 'grace', blockedBy: [] }
-  }
+  // Nobody is busy and no restart is pending: the countdown may run. There is
+  // no invisible reserve — the countdown on screen is the wait.
   return { allow: true, reason: 'quiet', blockedBy: [] }
 }
 
@@ -4290,11 +4581,11 @@ function createSleepService(ctx, runtime, config, options = {}) {
     busyAgents: () => runtime.busyAgents(),
     gate,
     titleOf: (sessionId) => runtime.sessionTitle(sessionId),
-    // The grace window: after the last conversation finished the machine
-    // waits a little longer, so that work this plugin cannot see (a memory
-    // plugin writing its notes, a summary) still gets its chance.
-    quietForMs: () => runtime.quietForMs(),
-    graceMs: () => runtime.graceMs(),
+    // The shutdown has NO invisible reserve: the countdown on screen IS the
+    // wait before the machine goes off. The controller keeps the parameter for
+    // compatibility, but the plugin never injects a window — and it never
+    // injects the RESTART reserve either.
+    graceMs: () => 0,
     // A pending restart goes first: the shutdown waits for it.
     restartPending: () => {
       const pending = runtime.pendingRestart()
@@ -4429,9 +4720,10 @@ function sleepStatusPayload(sleep, config, runtime) {
     armed: status.armed,
     showSleepButton: config.showSleepButton !== false,
     countdownSeconds: status.countdownSeconds,
-    // The grace window and how long the host has been quiet: both are needed
-    // to tell "the machine is waiting for the grace" from "somebody is busy".
-    graceMs: config.restartGraceMs,
+    // The RESTART reserve is reported next to the countdown, so the settings
+    // page can show it. The shutdown itself has NO invisible reserve: the
+    // visible countdown is the wait before the machine goes off.
+    restartGraceMs: config.restartGraceMs,
     quietForMs: runtime && typeof runtime.quietForMs === 'function' ? runtime.quietForMs() : 0,
     // When the shutdown was armed: the intent has to survive a restart, so the
     // time is reported for the troubleshooting.
@@ -4573,10 +4865,14 @@ function registerHealthRoute(ctx, runtime, config, sleep) {
           generation: state.generation,
           pendingRestart: state.restart !== null,
           settleMs: config.settleMs,
-          // The grace window and the quiet window the gate really uses: both
-          // are needed to tell "waiting for the grace" from "somebody is busy".
+          // The RESTART reserve and the quiet window the gate really uses:
+          // both are needed to tell "waiting for the reserve" from "somebody
+          // is busy".
           graceMs: config.restartGraceMs,
           effectiveSettleMs: runtime.effectiveSettleMs(),
+          // The upper bound of a queued (unclaimed) inbox message: after this
+          // window it stops blocking the restart.
+          queuedGraceMs: config.queuedGraceMs,
           quietForMs: typeof verdict.quietForMs === 'number' ? verdict.quietForMs : 0,
           busyCount: verdict.blockedBy.length,
           agentCount,
@@ -4639,11 +4935,23 @@ function registerHealthRoute(ctx, runtime, config, sleep) {
             waiters,
             blockedBy,
             allowRestart: verdict.allow === true,
+            // WHY the gate says what it says. Without this, "allowRestart is
+            // false and blockedBy is empty" looks like a contradiction: the
+            // reason tells the two apart (an empty blocker list with the
+            // reason "settling" means the quiet window is not full yet).
+            reason: typeof verdict.reason === 'string' ? verdict.reason : 'unknown',
             quietForMs: typeof verdict.quietForMs === 'number' ? verdict.quietForMs : 0,
             settleMs: config.settleMs,
-            // The grace window and the quiet window the gate really uses.
+            // The RESTART reserve and the quiet window the gate really uses.
             graceMs: config.restartGraceMs,
             effectiveSettleMs: runtime.effectiveSettleMs(),
+            // The upper bound of a queued (unclaimed) inbox message.
+            queuedGraceMs: config.queuedGraceMs,
+            // The long wait: present only when the restart passed the hard
+            // deadline while a conversation was still running. It says how
+            // long the restart has been waiting, why, and who holds it — the
+            // request itself is never dropped.
+            longWait: runtime.longWaitInfo(),
             updatedAt: live.updatedAt,
             // The park route, so the client never has to guess the prefix, and
             // the goals this plugin already disarmed (they are re-armed after
@@ -4669,7 +4977,10 @@ function registerHealthRoute(ctx, runtime, config, sleep) {
             waiters: [],
             blockedBy: [],
             allowRestart: false,
+            reason: 'unknown',
             quietForMs: 0,
+            queuedGraceMs: config.queuedGraceMs,
+            longWait: null,
             parkUrl: resolveParkPath(config),
             recoverUrl: resolveRecoverPath(config),
             choiceUrl: resolveChoicePath(config),
@@ -4838,9 +5149,20 @@ function trackAgents(ctx, runtime, config) {
     }
   })
 
-  // Any session event or newly queued inbox message restarts the settle window.
-  ctx.on('session/event', () => {
+  // A session event only restarts the settle window when it says that WORK
+  // happened (a message, a tool, a turn). The host produces session events
+  // every two to three seconds while the interface polls and synchronises —
+  // counting those as activity kept the quiet window from ever filling, so a
+  // restart with a grace window of ten seconds NEVER fired. When the type of
+  // an event cannot be read, it is not activity: the plugin would rather
+  // restart a little early than never restart at all.
+  //
+  // The hard guarantee is elsewhere and untouched: a conversation that is
+  // really running blocks the restart through `busyAgents()`, which is never
+  // relaxed.
+  ctx.on('session/event', (payload) => {
     try {
+      if (!isWorkSessionEvent(payload)) return
       runtime.noteActivity()
     } catch {}
   })