dsh-pause-resume 0.4.3 → 0.4.5

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # Changelog
 
+## 0.4.5
+
+A restore now leaves a durable record before every side effect, so a restart can finish it.
+
+* Before `goals.resume`, the plan records `pendingRestore` and writes it to disk. If the process dies
+  after the goal was armed but before the checkpoint was saved, the next boot sees the active,
+  disarmed goal and the intent that proves it is ours to re-arm. A goal is no longer reported as
+  `skipped` with an empty attention list after such a restart.
+* A goal whose state cannot be read is a retryable failure (`goal unreadable: …`) instead of being
+  treated as absent and consumed. Only a readable paused goal is resumed, and an unreadable goal is
+  never counted as work the pause can stop.
+* A crash plan on boot sets `phase` to `idle` and offers `resume`; it no longer claims the page is
+  paused. The dot still names the crash work through attention.
+* A pause plan that ended up in the crash slot can complete its restore, clear the slot and release
+  the heartbeat. It no longer leaves the button in `resuming`/`busy`.
+* Restore attention survives the consumed plan and is shown with a focused item id even when no work
+  is live. Killed jobs stay excluded from the dot.
+* A new pause bumps the continuation epoch only for the sessions it captured; rows owned by another
+  plan keep their request id.
+* A reload during a cold mount stops the old probe before it reports or prompts, so stale side
+  effects from a replaced instance cannot reach a session.
+* A full restore journals each item only after its outcome, and the plan is consumed only when every
+  item settled.
+
+## 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.
@@ -20,9 +64,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

@@ -2,12 +2,12 @@ import { homedir } from 'node:os'
 import { join } from 'node:path'
 import { createStore } from './lib/snapshot.js'
 import { createEngine } from './lib/engine.js'
-import { nextEpoch, dropEpoch } from './lib/epoch.js'
+import { nextEpoch, currentEpoch, dropEpoch } from './lib/epoch.js'
 import { createHeartbeat } from './lib/heartbeat.js'
 import { createProbe, listRunning } from './lib/probe.js'
 
 export const name = 'dsh-pause-resume'
-export const VERSION = '0.4.3'
+export const VERSION = '0.4.5'
 
 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),
     ],
   ]
@@ -216,6 +216,7 @@ export function apply(ctx, config = {}) {
     log,
   })
   const probe = createProbe(ctx, {
+    isCurrent: () => currentEpoch() === epoch,
     graceMs: Number.isFinite(config?.graceMs) ? config.graceMs : 2000,
     continueText: typeof config?.continueText === 'string' ? config.continueText : undefined,
   })
@@ -275,8 +276,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

@@ -28,6 +28,18 @@ function emptyLive() {
   return { sessions: [], goals: [], jobs: [], readable: false, source: 'none' }
 }
 
+/** One id for the hint: a restore attention row is either a label or a plan row. */
+function labelFocus(text) {
+  const match = /^(?:session|goal|job) ([^:]+):/.exec(String(text))
+  return match !== null ? match[1] : null
+}
+
+function attentionFocus(row) {
+  if (row === null || row === undefined) return null
+  if (typeof row === 'string') return labelFocus(row) ?? row.slice(0, 60) // ui-copy-ignore
+  return row.id || row.detail || null
+}
+
 /** One row per item: a retried stop must not multiply the same unfinished job in the dot. */
 function dedupeRows(rows) {
   const seen = new Set()
@@ -51,8 +63,12 @@ export function createEngine({ store, probe, heartbeat = null, bootId = 'boot',
   let result = null
   /** Set while a press runs, so a second caller joins the answer instead of starting work again. */
   let inflight = null
-  /** Crash plan kept in memory only when its durable write failed; a reload loses it, the file does not. */
-  let crashFallback = null
+  /**
+   * The complete plan kept in memory when its durable write failed. It can be a crash plan or a
+   * normal pause plan whose crash residue could not be merged; in both cases the file on disk is
+   * only an older subset and must not decide what this press restores.
+   */
+  let planFallback = null
   let counter = 0
 
   function newPlanId(kind) {
@@ -65,13 +81,45 @@ export function createEngine({ store, probe, heartbeat = null, bootId = 'boot',
   }
 
   function crashPlan() {
-    const stored = typeof store.readPending === 'function' ? store.readPending() : null
-    return stored ?? crashFallback
+    return typeof store.readPending === 'function' ? store.readPending() : null
   }
 
-  /** Exactly one plan is pending, and a finished pause outranks a leftover crash record. */
+  /**
+   * Exactly one plan is pending, and a finished pause outranks a leftover crash record. The
+   * in-memory fallback outranks both files: when a write failed it holds the complete work, while
+   * the older file would hide the half that was never saved.
+   */
   function currentPlan() {
-    return pausedPlan() ?? crashPlan()
+    return planFallback ?? pausedPlan() ?? crashPlan()
+  }
+
+  /** Identity and content of one plan, used to find which store actually holds it. */
+  function samePlan(left, right) {
+    return left !== null && right !== null && left.planId === right.planId && planKey(left) === planKey(right)
+  }
+
+  /** 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 (planFallback === plan) return true
+    // A plan can live in either file: a crash plan converted to a pause plan may have fallen back
+    // to pending.json when snapshot.json could not be written. Find it by content, not by source.
+    return samePlan(pausedPlan(), plan) || samePlan(crashPlan(), plan)
   }
 
   function isCrashPlan(plan) {
@@ -141,6 +189,16 @@ export function createEngine({ store, probe, heartbeat = null, bootId = 'boot',
     return work.sessions.length + work.goals.length + work.jobs.length
   }
 
+  /** The item a partial restore could not finish, so the tooltip can name it. */
+  function failureFocus(summary) {
+    for (const line of Array.isArray(summary?.failed) ? summary.failed : []) {
+      const match = /^(?:session|goal) ([^:]+):/.exec(String(line))
+      if (match !== null) return match[1]
+      if (typeof line === 'string' && line !== '') return line.slice(0, 60) // ui-copy-ignore
+    }
+    return null
+  }
+
   /**
    * What the button shows. `action` is the one decision the client may not make itself:
    * `none` (nothing to do), `pause`, `resume`, or `busy` (an operation is running).
@@ -159,14 +217,17 @@ export function createEngine({ store, probe, heartbeat = null, bootId = 'boot',
     if (busy) action = 'busy'
     else if (plan !== null) action = 'resume'
     else if (current.readable === true && workCount > 0) action = 'pause'
-    // The dot means "something still needs you". A clean idle page has nothing to point at: the
-    // jobs a pause killed stay in the last-restore record, but they are not an open obligation.
-    const attentionRows = plan !== null
-      ? dedupeRows(Array.isArray(plan.attention) ? plan.attention : [])
-      : phase === 'idle' && lastError === null ? null : result?.attention
-    const attention = Array.isArray(attentionRows) ? attentionRows.length : 0
+    // The dot means "something still needs you". Stopped jobs are reported separately and must not
+    // turn a clean idle page into a permanent dot, but restore attention also covers "the message
+    // was admitted and no turn started" and "the turn cannot be proven finished": those are open
+    // obligations even when no plan is left, so they are always shown.
+    const attentionRows = dedupeRows([
+      ...(Array.isArray(plan?.attention) ? plan.attention : []),
+      ...(Array.isArray(result?.attention) ? result.attention : []),
+    ])
+    const attention = attentionRows.length
     const first = attention > 0 ? attentionRows[0] : null
-    const focus = first === null ? null : (typeof first === 'string' ? first : (first.id || first.detail || null))
+    const focus = first !== null ? attentionFocus(first) : failureFocus(result)
     return {
       phase,
       action,
@@ -245,17 +306,20 @@ export function createEngine({ store, probe, heartbeat = null, bootId = 'boot',
     return out
   }
 
+  /** Which durable file currently holds this plan; a converted pause plan may still live in pending. */
+  function usesPending(plan) {
+    if (isCrashPlan(plan) === true) return true
+    return samePlan(crashPlan(), plan) && !samePlan(pausedPlan(), plan)
+  }
+
   function persist(plan) {
     if (isCurrent() === false) {
       log('stale instance: refusing to write over a newer plan')
       return null
     }
-    if (isCrashPlan(plan) === true) {
-      const stored = store.writePending(plan)
-      if (stored !== null) crashFallback = null
-      return stored
-    }
-    return store.write(plan)
+    const stored = usesPending(plan) ? store.writePending(plan) : store.write(plan)
+    if (stored !== null) planFallback = null
+    return stored
   }
 
   /**
@@ -292,8 +356,12 @@ export function createEngine({ store, probe, heartbeat = null, bootId = 'boot',
     const before = new Map((basePlan?.sessions ?? []).filter((row) => typeof row?.sessionId === 'string').map((row) => [row.sessionId, row]))
     const restoredBefore = Number.isSafeInteger(basePlan?.restore?.attempts) && basePlan.restore.attempts > 0
     plan.sessions = unionSessions(plan.sessions ?? [], work.sessions.map(freshSession))
+    // Only rows this press actually captured may get a new cycle. A row left from an earlier
+    // restore attempt belongs to a different pause: incrementing it would change its request id
+    // and admit a second continuation while the first is still sitting in the queue.
+    const captured = new Set(work.sessions.map((session) => session.sessionId))
     plan.sessions = plan.sessions.map((row) => {
-      if (row.intent !== 'continue') return row
+      if (row.intent !== 'continue' || captured.has(row.sessionId) === false) return row
       const prior = before.get(row.sessionId)
       const priorEpoch = Number.isSafeInteger(prior?.epoch) ? prior.epoch : 0
       if (Number.isSafeInteger(row.epoch) && row.epoch > priorEpoch) return row
@@ -373,16 +441,21 @@ export function createEngine({ store, probe, heartbeat = null, bootId = 'boot',
       // The crash record described work that was not paused. This press did pause it, so the plan
       // becomes a normal pause plan and the crash evidence is no longer a separate obligation.
       plan.source = 'pause' // ui-copy-ignore
-      if (store.write(plan) === null) {
-        const kept = store.writePending(plan)
+      // The two files are a migration, not a plain write: if snapshot.json cannot be written, the
+      // pending fallback is the only durable copy. Removing it after a failed snapshot write would
+      // discard the plan, and reading only snapshot.json would then call this plan a stranger.
+      if (store.write(plan) !== null) {
+        planFallback = null
+        if (typeof store.clearPending === 'function' && store.clearPending() === false) lastError = 'store'
+      } else {
+        const kept = typeof store.writePending === 'function' ? store.writePending(plan) : null
         if (kept === null) {
-          crashFallback = plan
+          planFallback = plan
           lastError = 'store'
+        } else {
+          planFallback = null
         }
-      } else if (typeof store.clearPending === 'function') {
-        if (store.clearPending() === false) lastError = 'store'
       }
-      crashFallback = null
     } else if (store.write(plan) === null) {
       // The durable copy still says `pausing` or `paused`: the next boot reports it instead of
       // claiming a stop that was never written.
@@ -408,7 +481,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 +502,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 +512,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
@@ -459,21 +539,64 @@ export function createEngine({ store, probe, heartbeat = null, bootId = 'boot',
     // flight turns a long serial restore into one batch without flooding the Harness.
     await Promise.all(Array.from({ length: Math.min(4, sessionRows.length) }, sessionWorker))
     for (const goal of plan.goals ?? []) {
+      if (stale()) break
       const key = `g:${goal.sessionId}:${goal.goalId ?? ''}`
-      const outcome = await step(key, `goal ${goal.goalId ?? goal.sessionId}`, () => probe.restoreGoal(goal, { plan }))
+      const label = `goal ${goal.goalId ?? goal.sessionId}`
+      const setGoal = (change) => {
+        plan.goals = (plan.goals ?? []).map((row) => (row.sessionId === goal.sessionId && row.goalId === goal.goalId
+          ? { ...row, ...change }
+          : row))
+      }
+      // Persist the intent before the side effect. A crash or a checkpoint failure after
+      // `goals.resume()` leaves an active, disarmed goal on the next boot; without this record the
+      // plan cannot prove that goal was its own work and would silently skip it.
+      if (goal.pendingRestore === undefined || goal.pendingRestore === null) {
+        setGoal({ pendingRestore: { revision: Number.isSafeInteger(goal.revision) ? goal.revision : null, at: now() } }) // ui-copy-ignore
+        if (persist(plan) === null) {
+          summary.failed.push(`${label}: restore intent not saved`)
+          lastError = 'store'
+          phase = 'paused'
+          return { status: 'partial', summary, outstanding: outstandingOf(plan) }
+        }
+      }
+      const outcome = await step(key, label, () => probe.restoreGoal(goal, { plan }))
+      if (outcome?.status === 'reloaded') break
       if (outcome?.status === 'restored' && Number.isSafeInteger(outcome.revision)) {
         // Remember what this plan armed. A restarted process sees `active + disarmed`, and that
         // exact revision is the only proof the goal is ours to arm again rather than someone else's.
-        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'
+        const row = (plan.goals ?? []).find((item) => item.sessionId === goal.sessionId && item.goalId === goal.goalId)
+        setGoal({ armedRevision: outcome.revision, pendingRestore: null })
+        if (persist(plan) === null) {
+          // Keep the intent on disk so the next boot can still re-arm the goal; returning partial
+          // without it was exactly how a successful resume became a silent skip after a restart.
+          setGoal({ armedRevision: row?.armedRevision ?? null, pendingRestore: goal.pendingRestore ?? { revision: Number.isSafeInteger(goal.revision) ? goal.revision : null, at: now() } })
+          summary.failed.push(`${label}: checkpoint not saved`)
+          lastError = 'store'
+          phase = 'paused'
+          return { status: 'partial', summary, outstanding: outstandingOf(plan) }
+        }
+      } else if (outcome?.status === 'restored' || TERMINAL.has(outcome?.status)) {
+        // Restored without a revision, or terminal for another reason: the intent is spent.
+        setGoal({ pendingRestore: null })
+        if (persist(plan) === null) {
+          summary.failed.push(`${label}: 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
@@ -483,35 +606,62 @@ export function createEngine({ store, probe, heartbeat = null, bootId = 'boot',
       return { status: 'partial', summary, outstanding: outstandingOf(plan) }
     }
 
-    if (isCrashPlan(plan) === true) {
-      if (typeof store.writeResult === 'function' && store.writeResult({ ...plan, status: 'restored', restoredAt: summary.at, summary }) === false) {
+    // A pending copy of the same plan means the migration's cleanup failed after snapshot.json was
+    // written. Finish that cleanup before consuming, or the next boot would offer the same restore
+    // again from a plan that is already complete.
+    if (usesPending(plan) === false && samePlan(crashPlan(), plan) && typeof store.clearPending === 'function') {
+      if (store.clearPending() === false) {
         lastError = 'store'
         phase = 'paused'
+        return { status: 'partial', summary, outstanding: outstandingOf(plan) }
+      }
+    }
+    // A plan may live in pending.json even after it became a normal pause plan (the snapshot
+    // write failed during the crash-to-pause migration). Completion follows the file that holds it.
+    if (usesPending(plan)) {
+      if (stillMine(plan) === false) {
+        log('stale instance: crash record left alone')
+        phase = 'paused'
         return { status: 'partial', summary, outstanding: 0 }
       }
-      if (typeof store.clearPending !== 'function' || store.clearPending() === false) {
+      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 }
       }
-      crashFallback = null
-      if (typeof store.clearJournal === 'function') store.clearJournal(plan.planId)
-      if (isCurrent() === false) {
+      if (stillMine(plan) === false) {
         log('stale instance: crash record left alone')
+        phase = 'paused'
         return { status: 'partial', summary, outstanding: 0 }
       }
-      try {
-        heartbeat?.release?.()
-      } catch (error) {
-        log(`cannot release crash record: ${error?.message ?? error}`)
+      if (typeof store.clearPending !== 'function' || store.clearPending() === false) {
+        lastError = 'store'
+        phase = 'paused'
+        return { status: 'partial', summary, outstanding: 0 }
       }
+      planFallback = null
+      if (typeof store.clearJournal === 'function') store.clearJournal(plan.planId)
     } else {
+      if (stillMine(plan) === false) {
+        log('stale instance: pause plan left alone')
+        phase = 'paused'
+        return { status: 'partial', summary, outstanding: 0 }
+      }
       const consumed = store.consume(plan, summary)
       if (!consumed?.ok) {
         lastError = 'store'
         phase = 'paused'
         return { status: 'partial', summary, outstanding: 0 }
       }
+      planFallback = null
+    }
+    // The plan is complete, including every crash row that was merged into it. Only now may the
+    // heartbeat stop protecting the previous process's record: releasing earlier would overwrite
+    // the only evidence of a session the merge had not yet brought into this plan.
+    try {
+      heartbeat?.release?.()
+    } catch (error) {
+      log(`cannot release heartbeat: ${error?.message ?? error}`)
     }
     phase = 'idle'
     return { status: 'resumed', summary }
@@ -568,7 +718,7 @@ export function createEngine({ store, probe, heartbeat = null, bootId = 'boot',
    * overwrites the previous process's file; it is persisted here so a second restart still sees it.
    */
   async function hydrate(options = {}) {
-    crashFallback = null
+    planFallback = null
     lastError = null
     const residue = options?.residue ?? heartbeat?.residue ?? null
     const restored = typeof store.lastRestore === 'function' ? store.lastRestore() : null
@@ -591,7 +741,7 @@ export function createEngine({ store, probe, heartbeat = null, bootId = 'boot',
           // A failed write stays in memory for this process, but the caller must not let the
           // heartbeat overwrite the file the next process would have read the same residue from.
           if (stored === null) {
-            crashFallback = crash
+            planFallback = crash
             durable = false
             lastError = 'store'
             heartbeat?.hold?.()
@@ -624,10 +774,13 @@ export function createEngine({ store, probe, heartbeat = null, bootId = 'boot',
             if (stored === null) {
               durable = false
               lastError = 'store'
-              if (isCrash) crashFallback = plan
+              // Whatever the source, the in-memory plan now holds the complete set. Resume must
+              // use it, or the sessions that only exist here would be skipped forever.
+              planFallback = plan
               heartbeat?.hold?.()
               log('cannot merge the crash plan; keeping the previous heartbeat')
             } else {
+              planFallback = null
               log(`crash sessions merged (${added.length})`)
             }
           }
@@ -635,7 +788,9 @@ export function createEngine({ store, probe, heartbeat = null, bootId = 'boot',
       }
     }
 
-    phase = pausedPlan() !== null ? 'paused' : 'idle'
+    const hydrated = currentPlan()
+    // A crash record is not a pause: the button offers restore, but the page is not paused.
+    phase = hydrated !== null && isCrashPlan(hydrated) === false ? 'paused' : 'idle'
     return { phase, durable }
   }
 

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

@@ -76,9 +76,12 @@ function goalView(services, agent) {
   if (goals === undefined || goals === null || typeof goals.get !== 'function') return undefined
   try {
     const view = goals.get(agent)
-    return view === undefined || view === null ? undefined : view
-  } catch {
-    return undefined
+    // `null` is the service's answer for "no goal"; a throw is "cannot tell right now". Collapsing
+    // both into `undefined` made a transient read error look like the goal had been deleted, which
+    // the restore then recorded as a terminal skip and never retried.
+    return view === undefined || view === null ? null : view
+  } catch (error) {
+    return { unreadable: true, detail: String(error?.message ?? error).slice(0, 120) }
   }
 }
 
@@ -132,6 +135,10 @@ export function createProbe(services, options = {}) {
   const continueText = typeof options.continueText === 'string' && options.continueText.trim() !== ''
     ? options.continueText
     : '继续'
+  // A reload replaces the probe while an old restore is still awaiting a mount. The old probe must
+  // stop before its side effects, not after: a sent message cannot be taken back.
+  const isCurrent = typeof options.isCurrent === 'function' ? options.isCurrent : () => true
+  const reloaded = () => isCurrent() === false
 
   /** Everything this press can stop, read from the live registry only. */
   function live() {
@@ -151,7 +158,7 @@ export function createProbe(services, options = {}) {
       sessions.push({ sessionId: agent.id, running: agent.status === 'running', lastTurn: lastTurnOf(agent) })
       // A disarmed goal is not work: it will not start a round, and pausing it would throw. Only an
       // active, armed goal is something this press can stop and this restore can re-arm.
-      if (goal !== undefined && goal.phase === 'active' && goal.activation === 'armed') {
+      if (goal !== undefined && goal !== null && goal.unreadable !== true && goal.phase === 'active' && goal.activation === 'armed') {
         goals.push({ sessionId: agent.id, goalId: goal.id, revision: goal.revision })
       }
       for (const job of owned) if (RUNNING_JOB.has(job.status)) jobs.push({ id: job.id, owner: agent.id, status: job.status })
@@ -236,10 +243,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',
@@ -288,6 +300,7 @@ export function createProbe(services, options = {}) {
         return { status: 'failed', detail }
       }
     }
+    if (reloaded()) return { status: 'reloaded' }
 
     // Version 2 plans carry only `running`; a normalized version 3 plan carries `intent`. Reading
     // the old field here keeps a plan written by 0.3.0 working across the upgrade.
@@ -312,6 +325,7 @@ export function createProbe(services, options = {}) {
     if (controller === undefined || controller === null || typeof controller.prompt !== 'function') {
       return { status: 'failed', detail: 'prompt unavailable', continued: false }
     }
+    if (reloaded()) return { status: 'reloaded' }
     const request = continuation(plan, sessionId, session.epoch)
     try {
       // Two arguments: the shipped service takes the caller's AbortSignal. Passing source metadata
@@ -356,12 +370,16 @@ export function createProbe(services, options = {}) {
         return { status: 'failed', detail: String(error?.message ?? error).slice(0, 120) }
       }
     }
+    if (reloaded()) return { status: 'reloaded' }
     const services_goals = service(services, 'goals')
     if (services_goals === undefined || services_goals === null || typeof services_goals.resume !== 'function') {
       return { status: 'failed', detail: 'goals unavailable' }
     }
     const view = goalView(services, agent)
-    if (view === undefined || (typeof goal.goalId === 'string' && view.id !== goal.goalId)) {
+    if (view !== undefined && view !== null && view.unreadable === true) {
+      return { status: 'failed', detail: `goal unreadable: ${view.detail}` }
+    }
+    if (view === undefined || view === null || (typeof goal.goalId === 'string' && view.id !== goal.goalId)) {
       return { status: 'skipped', detail: 'goal is gone' }
     }
     // An active goal is normally not ours to touch. The one exception is a goal this same plan
@@ -369,13 +387,22 @@ export function createProbe(services, options = {}) {
     // exactly the revision the plan recorded. Another person's goal has no such record.
     if (view.phase === 'active') {
       if (view.activation === 'armed') return { status: 'skipped', detail: 'already active' }
-      if (Number.isSafeInteger(goal.armedRevision) && goal.armedRevision === view.revision) {
+      const pending = goal.pendingRestore !== null && typeof goal.pendingRestore === 'object' ? goal.pendingRestore : null
+      const pendingRevision = Number.isSafeInteger(pending?.revision) ? pending.revision : null
+      // `pendingRestore` was written before the side effect. If the process died after resume but
+      // before the checkpoint, the goal is active and disarmed at the revision our resume produced.
+      const ours = pending !== null && (pendingRevision === null || view.revision >= pendingRevision)
+      if (ours || (Number.isSafeInteger(goal.armedRevision) && goal.armedRevision === view.revision)) {
+        if (reloaded()) return { status: 'reloaded' }
         try {
           services_goals.resume(agent, { id: view.id, revision: view.revision })
         } catch (error) {
           return { status: 'failed', detail: String(error?.message ?? error).slice(0, 120) }
         }
         const after = goalView(services, agent)
+        if (after !== undefined && after !== null && after.unreadable === true) {
+          return { status: 'failed', detail: 'goal unreadable after resume' }
+        }
         return { status: 'restored', detail: 're-armed after restart', revision: after?.revision ?? null }
       }
       return { status: 'skipped', detail: 'goal disarmed' }
@@ -390,12 +417,16 @@ export function createProbe(services, options = {}) {
     const expected = Number.isSafeInteger(goal.revision) ? goal.revision : goal.pausedRevision
     if (Number.isSafeInteger(expected) === false) return { status: 'attention', detail: 'goal has no saved revision' }
     if (view.revision !== expected) return { status: 'skipped', detail: 'goal changed by hand' }
+    if (reloaded()) return { status: 'reloaded' }
     try {
       services_goals.resume(agent, { id: view.id, revision: view.revision })
     } catch (error) {
       return { status: 'failed', detail: String(error?.message ?? error).slice(0, 120) }
     }
     const after = goalView(services, agent)
+    if (after !== undefined && after !== null && after.unreadable === true) {
+      return { status: 'failed', detail: 'goal unreadable after resume' }
+    }
     return { status: 'restored', detail: 'armed', revision: after?.revision ?? null }
   }
 

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.3",
+  "version": "0.4.5",
   "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",