dsh-pause-resume 0.4.2 → 0.4.4

package/CHANGELOG.md

@@ -1,6 +1,26 @@
 # Changelog
 
-## 0.4.2
+## 0.4.4
+
+Restores are now safe to hand over between instances and across an upgrade.
+
+* An interrupted pause resets the whole restore policy (`intent: "mount"`, `epoch: 0`), so it is
+  mounted and never sends a continuation.
+* When a merged crash plan could not be written to disk, resume restores that in-memory plan, which
+  holds both the old and the newly found sessions. The older `pending.json` no longer wins and hides
+  half the work.
+* `heartbeat.release()` restores a full lifecycle: the periodic sample is re-armed, `stopped` is
+  cleared, and state events can persist again. Previously the file stayed frozen after a repaired
+  write failure.
+* A pre-epoch plan keeps its original continuation request id (`…:continue:<session>`), so upgrading
+  cannot queue a second copy of a message the old version already admitted.
+* A restore that loses ownership (plugin reload) stops before publishing, consuming or clearing. It
+  also compares the plan's actual work, not only its id, so additions from a newer press survive.
+* A goal whose checkpoint cannot be written keeps the plan on disk with the failure named, instead of
+  silently skipping the goal on the next boot.
+* The button hint combines the error with the focused item for partial pause/restore.
+
+## 0.4.3
 
 - The dot now means one thing: something is waiting on you (a paused plan with commands that will not restart, or a stop/restore that failed). A clean idle page has no dot, and killed jobs live in the restore record instead of becoming a permanent red light.
 - Restore mounts sessions in bounded parallel batches, so wall time is the slowest batch instead of the sum of every session.
@@ -20,9 +40,9 @@ A stop that could not finish no longer traps the button, and the dot stops lying
 
 The crash path is now a first-class restore path, and a dead button after a restart is fixed.
 
-* Routes are registered synchronously while `apply` runs. The web server freezes its route table
-  when it starts, so registering after `hydrate()` left the button answering 404 on a fresh boot.
-  Handlers now wait for hydration instead of the route table waiting for it.
+* Routes are registered synchronously while `apply` runs. Registration itself is not the problem —
+  the server keeps a live route table — but registering after hydration meant the button could be
+  pressed before the table had an entry. Handlers now wait for hydration instead.
 * A crash plan is written to `pending.json` before the heartbeat is replaced. If that write fails,
   the heartbeat is held and the previous `running.json` is left untouched, so the next boot still
   sees the work.

package/README.md

@@ -25,7 +25,9 @@ last press left something for a person to look at.
 
 Schedules are not paused: the schedule service has no disable operation, only delete, and deleting a
 person's schedule to pause it is not a trade this plugin makes. A schedule that fires while paused
-starts a turn; the button then shows ⏸ again, truthfully.
+starts a turn, but the button keeps showing ▶ while a pause plan waits: a pending plan owns the main
+action, so the only honest next step is to finish the restore. The schedule appears in that restore
+summary like any other work started after the press.
 
 ## How resume works
 

package/client.js

@@ -140,8 +140,9 @@ window.__ModuleLoader__.load({
 
     /** The one sentence behind the dot, in the tooltip only: the button itself stays a glyph. */
     function hintOf(state) {
-      if (state.error === 'restore-partial') return COPY.partial
-      if (state.error !== null && state.error !== undefined) return COPY.error
+      const focus = typeof state.focus === 'string' && state.focus !== '' ? state.focus : ''
+      if (state.error === 'restore-partial') return focus === '' ? COPY.partial : `${COPY.partial}: ${focus}`
+      if (state.error !== null && state.error !== undefined) return focus === '' ? COPY.error : `${COPY.error}: ${focus}`
       if ((state.attention ?? 0) > 0) {
         return typeof state.focus === 'string' && state.focus !== '' ? `${COPY.attention}: ${state.focus}` : COPY.attention
       }

package/index.js

@@ -7,7 +7,7 @@ import { createHeartbeat } from './lib/heartbeat.js'
 import { createProbe, listRunning } from './lib/probe.js'
 
 export const name = 'dsh-pause-resume'
-export const VERSION = '0.4.1'
+export const VERSION = '0.4.4'
 
 const BASE_PATH = '/dsh-pause-resume'
 const BUTTON_HEADER = 'x-dsh-pause-resume'
@@ -135,8 +135,8 @@ function serve(ctx, engine, heartbeat, options, ready) {
     if (read === true ? sameOrigin(req, allowRemote) === false : buttonAllowed(req, allowRemote) === false) {
       return sendJson(res, 403, { status: 'forbidden' })
     }
-    // Routes are registered synchronously so the server freezes them before it starts. Hydration
-    // may still be reading crash residue, so every press waits for it instead of acting blind.
+    // Routes are registered synchronously so no press can arrive before the table has them.
+    // Hydration may still be reading crash residue, so every press waits for it instead of acting blind.
     if (ready !== undefined) await ready
     if (disposed === true) return sendJson(res, 503, { status: 'starting' })
     return handler(req, res)
@@ -145,7 +145,7 @@ function serve(ctx, engine, heartbeat, options, ready) {
     [
       `${BASE_PATH}/state`,
       route(async (req, res) => {
-        sendJson(res, 200, engine.describe())
+        sendJson(res, 200, { ...engine.describe(), version: VERSION })
       }, true),
     ],
     [
@@ -154,7 +154,7 @@ function serve(ctx, engine, heartbeat, options, ready) {
         const outcome = await engine.pause()
         log(`pause: ${outcome.status}${outcome.status === 'busy' ? ` (${outcome.phase})` : ''}`)
         if (outcome.status === 'paused' || outcome.status === 'partial') heartbeat.release()
-        sendJson(res, 200, { ...engine.describe(), outcome })
+        sendJson(res, 200, { ...engine.describe(), outcome, version: VERSION })
       }, false),
     ],
     [
@@ -162,7 +162,7 @@ function serve(ctx, engine, heartbeat, options, ready) {
       route(async (req, res) => {
         const outcome = await engine.resume()
         log(`resume: ${outcome.status}`)
-        sendJson(res, 200, { ...engine.describe(), outcome })
+        sendJson(res, 200, { ...engine.describe(), outcome, version: VERSION })
       }, false),
     ],
   ]
@@ -275,8 +275,8 @@ export function apply(ctx, config = {}) {
     log(`cannot follow agent events: ${error?.message ?? error}`)
   }
 
-  // The server freezes its route table when it starts, so routes must be registered while `apply`
-  // is still synchronous. Hydration is asynchronous; the handlers wait on this promise.
+  // Routes must be registered while `apply` is still synchronous, so a press can never arrive
+  // before the table has an entry. Hydration is asynchronous; the handlers wait on this promise.
   let releaseReady = () => {}
   const ready = new Promise((resolve) => {
     releaseReady = resolve

package/lib/engine.js

@@ -66,7 +66,9 @@ export function createEngine({ store, probe, heartbeat = null, bootId = 'boot',
 
   function crashPlan() {
     const stored = typeof store.readPending === 'function' ? store.readPending() : null
-    return stored ?? crashFallback
+    // When the merge could not be written, the in-memory plan holds the old crash sessions *and*
+    // the ones this process found; the older file would hide the half that was never saved.
+    return crashFallback ?? stored
   }
 
   /** Exactly one plan is pending, and a finished pause outranks a leftover crash record. */
@@ -74,6 +76,32 @@ export function createEngine({ store, probe, heartbeat = null, bootId = 'boot',
     return pausedPlan() ?? crashPlan()
   }
 
+  /** The work a plan asks for, without timestamps or reporting fields. */
+  function planKey(plan) {
+    const row = (item) => [item?.sessionId ?? '', item?.intent ?? (item?.running === true ? 'continue' : 'mount'), item?.goalId ?? '']
+    return JSON.stringify({
+      sessions: (plan?.sessions ?? []).map(row),
+      goals: (plan?.goals ?? []).map((goal) => [goal?.sessionId ?? '', goal?.goalId ?? '']),
+      jobs: (plan?.jobs ?? []).map((job) => job?.id ?? ''),
+    })
+  }
+
+  /**
+   * A plan is only ours to spend if the durable copy still asks for exactly the same work. A
+   * merged plan keeps the planId, so an id comparison alone would delete another press's additions.
+   */
+  function stillMine(plan) {
+    if (isCurrent() === false) return false
+    // When the merge could not be written, this in-memory plan is the complete set and the file
+    // is only its older subset. The epoch check above already proved no newer instance wrote.
+    if (isCrashPlan(plan) === true && crashFallback === plan) return true
+    const current = isCrashPlan(plan)
+      ? (typeof store.readPending === 'function' ? store.readPending() : null)
+      : store.read()
+    if (current === null) return crashFallback === plan && isCrashPlan(plan) === true
+    return current.planId === plan.planId && planKey(current) === planKey(plan)
+  }
+
   function isCrashPlan(plan) {
     return plan !== null && plan !== undefined && plan.source === 'crash'
   }
@@ -408,7 +436,11 @@ export function createEngine({ store, probe, heartbeat = null, bootId = 'boot',
     if (plan.status === 'pausing') {
       plan.source = plan.source === 'crash' ? 'crash' : 'interrupted'
       plan.attention = [...(plan.attention ?? []), { kind: 'pause', id: '', detail: 'pause interrupted' }]
-      plan.sessions = (plan.sessions ?? []).map((session) => ({ ...session, running: false, lastTurn: null }))
+      // `intent` outranks `running` in the probe, so an interrupted pause must reset the whole
+      // policy: mount only, no admission, and no earlier cycle's request identity.
+      plan.sessions = (plan.sessions ?? []).map((session) => ({
+        ...session, intent: 'mount', running: false, epoch: 0, lastTurn: null,
+      }))
       plan.status = 'paused'
       if (persist(plan) === null) {
         phase = 'paused'
@@ -425,7 +457,9 @@ export function createEngine({ store, probe, heartbeat = null, bootId = 'boot',
         log(`cannot journal ${key}`)
       }
     }
+    const stale = () => isCurrent() === false
     const step = async (key, label, run) => {
+      if (stale()) return { status: 'failed', detail: 'reloaded' }
       let outcome
       try {
         outcome = await run()
@@ -433,6 +467,7 @@ export function createEngine({ store, probe, heartbeat = null, bootId = 'boot',
         outcome = { status: 'failed', detail: String(error?.message ?? error).slice(0, 120) }
       }
       const status = typeof outcome?.status === 'string' ? outcome.status : 'failed'
+      if (status === 'reloaded') return outcome
       if (TERMINAL.has(status) === false) {
         summary.failed.push(`${label}: ${outcome?.detail ?? 'unknown'}`)
         return outcome
@@ -467,13 +502,27 @@ export function createEngine({ store, probe, heartbeat = null, bootId = 'boot',
         plan.goals = (plan.goals ?? []).map((row) => (row.sessionId === goal.sessionId && row.goalId === goal.goalId
           ? { ...row, armedRevision: outcome.revision }
           : row))
-        if (persist(plan) === null) lastError = 'store'
+        if (persist(plan) === null) {
+          // Without the checkpoint a later boot cannot prove this goal is ours to arm again.
+          // Keep the plan (sessions mount idempotently) instead of silently skipping the goal.
+          summary.failed.push(`goal ${goal.goalId ?? goal.sessionId}: checkpoint not saved`)
+          lastError = 'store'
+          phase = 'paused'
+          return { status: 'partial', summary, outstanding: outstandingOf(plan) }
+        }
       }
     }
     // A killed job cannot be replayed: the same command may have had an unknown effect, so it is
     // reported once and left to the person. It never blocks the plan and is never restarted.
     for (const job of plan.jobs ?? []) summary.jobsStopped.push(`job ${job.id}: stopped, not restarted`)
 
+    if (stale()) {
+      // A reload owns the plan now. Publishing a summary or consuming anything here would erase
+      // work the new instance captured while these mounts were in flight.
+      log('stale instance: restore result discarded')
+      return { status: 'partial', summary, outstanding: outstandingOf(plan) }
+    }
+
     result = summary
     if (summary.failed.length > 0) {
       plan.restore = { at: summary.at, attempts: (plan.restore?.attempts ?? 0) + 1, failed: summary.failed } // ui-copy-ignore
@@ -484,11 +533,19 @@ export function createEngine({ store, probe, heartbeat = null, bootId = 'boot',
     }
 
     if (isCrashPlan(plan) === true) {
+      if (stillMine(plan) === false) {
+        log('stale instance: crash record left alone')
+        return { status: 'partial', summary, outstanding: 0 }
+      }
       if (typeof store.writeResult === 'function' && store.writeResult({ ...plan, status: 'restored', restoredAt: summary.at, summary }) === false) {
         lastError = 'store'
         phase = 'paused'
         return { status: 'partial', summary, outstanding: 0 }
       }
+      if (stillMine(plan) === false) {
+        log('stale instance: crash record left alone')
+        return { status: 'partial', summary, outstanding: 0 }
+      }
       if (typeof store.clearPending !== 'function' || store.clearPending() === false) {
         lastError = 'store'
         phase = 'paused'
@@ -496,16 +553,16 @@ export function createEngine({ store, probe, heartbeat = null, bootId = 'boot',
       }
       crashFallback = null
       if (typeof store.clearJournal === 'function') store.clearJournal(plan.planId)
-      if (isCurrent() === false) {
-        log('stale instance: crash record left alone')
-        return { status: 'partial', summary, outstanding: 0 }
-      }
       try {
         heartbeat?.release?.()
       } catch (error) {
         log(`cannot release crash record: ${error?.message ?? error}`)
       }
     } else {
+      if (stillMine(plan) === false) {
+        log('stale instance: pause plan left alone')
+        return { status: 'partial', summary, outstanding: 0 }
+      }
       const consumed = store.consume(plan, summary)
       if (!consumed?.ok) {
         lastError = 'store'

package/lib/heartbeat.js

@@ -204,16 +204,21 @@ export function createHeartbeat({ dir, bootId, intervalMs = 5000, listRunning, n
     }
   }
 
+  function arm() {
+    if (timer !== null) return
+    timer = setInterval(() => {
+      void refresh()
+    }, intervalMs)
+    if (typeof timer.unref === 'function') timer.unref()
+  }
+
   function start() {
     if (started) return
     started = true
     stopped = false
     capture()
     void refresh()
-    timer = setInterval(() => {
-      void refresh()
-    }, intervalMs)
-    if (typeof timer.unref === 'function') timer.unref()
+    arm()
   }
 
   function stop() {
@@ -234,10 +239,23 @@ export function createHeartbeat({ dir, bootId, intervalMs = 5000, listRunning, n
     stop()
   }
 
-  /** The residue was restored: from here on the heartbeat describes this process again. */
+  /**
+   * The residue was restored: this process owns the file again. Clear `stopped`, re-arm the timer
+   * and allow `note()`; a permission flip alone would leave both write paths dead.
+   */
   function release() {
     writable = true
     residue = null
+    started = true
+    stopped = false
+    if (dirty() && noteTimer === null) {
+      noteTimer = setTimeout(() => {
+        noteTimer = null
+        void flush()
+      }, DEBOUNCE_MS)
+      if (typeof noteTimer.unref === 'function') noteTimer.unref()
+    }
+    arm()
     void refresh(true)
   }
 

package/lib/probe.js

@@ -236,10 +236,15 @@ export function createProbe(services, options = {}) {
     // The epoch is the pause cycle. A retry of the same pause reuses the id (official dedupe keeps
     // admission idempotent), while a new pause after a partial restore gets a fresh one, so the
     // earlier admitted message cannot swallow this cycle's continuation.
-    const cycle = Number.isSafeInteger(epoch) && epoch > 0 ? epoch : 1
+    const cycle = Number.isSafeInteger(epoch) && epoch >= 0 ? epoch : 1
+    // Cycle 0 is a pre-epoch plan: keep the exact id that may already sit in the official queue,
+    // so upgrading the plugin cannot duplicate a continuation the old version admitted.
+    const requestId = cycle === 0
+      ? `${plan.planId}:continue:${sessionId}`
+      : `${plan.planId}:continue:${sessionId}:${cycle}`
     return {
       sessionId,
-      requestId: `${plan.planId}:continue:${sessionId}:${cycle}`,
+      requestId,
       content: [{ type: 'text', text: continueText }],
       // `queue` is the shipped public mode: deliver after the current turn, start one when idle.
       mode: 'queue',

package/lib/snapshot.js

@@ -152,9 +152,9 @@ export function createStore(dir, options = {}) {
       const intent = row.intent === 'continue' || row.intent === 'mount'
         ? row.intent
         : (row.running === true ? 'continue' : 'mount')
-      const epoch = Number.isSafeInteger(row.epoch) && row.epoch > 0
-        ? row.epoch
-        : (intent === 'continue' ? 1 : 0)
+      // A plan written before epochs existed has no cycle number. Zero is the legacy identity:
+      // the continuation keeps its original request id instead of looking like a new operation.
+      const epoch = Number.isSafeInteger(row.epoch) && row.epoch > 0 ? row.epoch : 0
       return { ...row, intent, epoch, running: intent === 'continue' }
     })
     plan.goals = (Array.isArray(plan.goals) ? plan.goals : []).map((row) => (

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-pause-resume",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "type": "module",
   "description": "One header button stops running turns, goals and jobs, writes a plan to disk, and restores that work after a restart or crash; the button shape is the only status.",
   "license": "MIT",