dsh-pause-resume 0.3.0 → 0.4.1

package/CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+## 0.4.1
+
+A stop that could not finish no longer traps the button, and the dot stops lying after a resume.
+
+* An unfinished stop now always offers the resume that releases it. The button used to prefer
+  `pause` whenever live work remained, so a partial stop re-ran the same stop on the same
+  uncancellable turn: the icon never changed, the attention dot stayed, and pressing it did
+  nothing a person could see.
+* Work that starts while a plan waits no longer flips the button back to pause. The plan owns the
+  action until it is consumed.
+## 0.4.0
+
+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.
+* 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.
+* Crash rows record `intent: "mount"` and are mounted only; they can never turn into a continuation
+  by accident. A pause row records `intent: "continue"`.
+* A subagent session that cannot be mounted directly is reported once as attention for its parent,
+  not retried forever as a failure that keeps the plan open.
+* Partial pauses and partial restores name the first item that needs a person in `focus`, so the
+  button's dot has an explanation without adding text to the button.
+* A hot reload bumps a shared epoch; an old instance's in-flight press can no longer overwrite the
+  plan written by the new instance.
+* A continuation request id gets a new epoch after a restore attempt, so pausing again after a
+  partial restore is not silently deduplicated by the Host.
+* Directed regression tests for the route-registration order, crash-plan durability, subagent rows
+  and stale-instance writes.
+
+## 0.3.0
+
+* Crash residue is turned into a plan and offered as a restore, with no press needed.
+* Version 3 plans distinguish mount-only crash rows from continuation rows.
+* Restores re-check live state instead of trusting the journal.
+
+## 0.2.0
+
+* One header button: pause stops turns, goals and jobs; resume restores them after a restart.
+* Durable snapshots, per-item outcomes, journaled restore attempts.
+
+## 0.1.0
+
+* First release.

package/README.md

@@ -46,6 +46,9 @@ request id is derived from the plan and the session, so a retry before a turn st
 by the Host. A failure leaves the plan on disk and the next press retries every item that still needs
 work.
 
+A subagent session cannot be mounted by this process: its parent chat owns the routing. That row is
+reported once as attention for the parent, not retried as a failure, so it never keeps the plan open.
+
 ## Crash, not just a press
 
 A press writes a snapshot. A crash writes nothing, so the plugin keeps a heartbeat instead:

package/client.js

@@ -43,6 +43,7 @@ window.__ModuleLoader__.load({
       counts: { sessions: 0, goals: 0, jobs: 0 },
       live: { sessions: 0, goals: 0, jobs: 0 },
       attention: 0,
+      focus: null, // ui-copy-ignore
       error: null, // ui-copy-ignore
     }
 
@@ -141,7 +142,9 @@ window.__ModuleLoader__.load({
     function hintOf(state) {
       if (state.error === 'restore-partial') return COPY.partial
       if (state.error !== null && state.error !== undefined) return COPY.error
-      if ((state.attention ?? 0) > 0) return COPY.attention
+      if ((state.attention ?? 0) > 0) {
+        return typeof state.focus === 'string' && state.focus !== '' ? `${COPY.attention}: ${state.focus}` : COPY.attention
+      }
       if ((state.outstanding ?? 0) > 0) return COPY.stopped
       return ''
     }

package/index.js

@@ -2,11 +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 { createHeartbeat } from './lib/heartbeat.js'
 import { createProbe, listRunning } from './lib/probe.js'
 
 export const name = 'dsh-pause-resume'
-export const VERSION = '0.3.0'
+export const VERSION = '0.4.1'
 
 const BASE_PATH = '/dsh-pause-resume'
 const BUTTON_HEADER = 'x-dsh-pause-resume'
@@ -117,13 +118,14 @@ function guard(handler) {
   }
 }
 
-function serve(ctx, engine, heartbeat, options) {
+function serve(ctx, engine, heartbeat, options, ready) {
   const server = service(ctx, 'webServer')
   if (server === undefined || server === null || typeof server.register !== 'function') {
     log('no web server: the header button cannot ask for a pause')
     return () => {}
   }
   const allowRemote = options.allowRemote === true
+  let disposed = false
   const route = (handler, read) => guard(async (req, res) => {
     const method = String(req?.method ?? 'GET').toUpperCase()
     if (read === true ? method !== 'GET' && method !== 'HEAD' : method !== 'POST') {
@@ -133,6 +135,10 @@ function serve(ctx, engine, heartbeat, options) {
     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.
+    if (ready !== undefined) await ready
+    if (disposed === true) return sendJson(res, 503, { status: 'starting' })
     return handler(req, res)
   })
   const handlers = [
@@ -170,6 +176,7 @@ function serve(ctx, engine, heartbeat, options) {
     }
   }
   return () => {
+    disposed = true
     for (const dispose of disposers) {
       try {
         dispose()
@@ -212,10 +219,12 @@ export function apply(ctx, config = {}) {
     graceMs: Number.isFinite(config?.graceMs) ? config.graceMs : 2000,
     continueText: typeof config?.continueText === 'string' ? config.continueText : undefined,
   })
+  const epoch = nextEpoch()
   const engine = createEngine({
     store,
     probe,
     heartbeat,
+    epoch,
     bootId: bootId(),
     graceMs: Number.isFinite(config?.graceMs) ? config.graceMs : 2000,
     log,
@@ -225,6 +234,8 @@ export function apply(ctx, config = {}) {
   let disposeRoutes = () => {}
   const cleanup = () => {
     disposed = true
+    // The in-flight press, if any, checks this and refuses to write its stale result.
+    dropEpoch(epoch)
     try {
       disposeRoutes()
     } catch {}
@@ -264,21 +275,35 @@ 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.
+  let releaseReady = () => {}
+  const ready = new Promise((resolve) => {
+    releaseReady = resolve
+  })
+  const dispose = serve(ctx, engine, heartbeat, { allowRemote }, ready)
+  if (disposed) dispose()
+  else disposeRoutes = dispose
+
   void (async () => {
     try {
       // Read the previous process's record before `start()` overwrites it, and persist the crash
       // plan before the heartbeat goes away: a second restart then still sees the same work.
       const residue = heartbeat.peek()
-      await engine.hydrate({ residue })
+      const hydrated = await engine.hydrate({ residue })
       if (disposed) return
+      // Only overwrite the previous process's record after the residue is durable. Otherwise the
+      // next boot would read this process's nearly-empty heartbeat and lose the work entirely.
+      if (hydrated?.durable === false) {
+        log('crash residue is not durable; heartbeat not started')
+        return
+      }
       heartbeat.start()
-      if (disposed) return
-      const dispose = serve(ctx, engine, heartbeat, { allowRemote })
-      if (disposed) dispose()
-      else disposeRoutes = dispose
       log(`ready (${engine.phase})`)
     } catch (error) {
       log(`cannot start: ${error?.message ?? error}`)
+    } finally {
+      releaseReady()
     }
   })()
 

package/lib/engine.js

@@ -19,6 +19,8 @@
  * still sees the same pending work.
  */
 
+import { currentEpoch } from './epoch.js'
+
 const TRANSIENT = new Set(['pausing', 'resuming'])
 const TERMINAL = new Set(['restored', 'skipped', 'attention'])
 
@@ -26,7 +28,12 @@ function emptyLive() {
   return { sessions: [], goals: [], jobs: [], readable: false, source: 'none' }
 }
 
-export function createEngine({ store, probe, heartbeat = null, bootId = 'boot', now = () => Date.now(), graceMs = 2000, log = () => {} }) {
+export function createEngine({ store, probe, heartbeat = null, bootId = 'boot', epoch = null, now = () => Date.now(), graceMs = 2000, log = () => {} }) {
+  /**
+   * A reload creates a new instance and bumps the shared epoch. An old instance's press may still
+   * be awaiting a cancelled turn; it must not write its stale plan over the new instance's one.
+   */
+  const isCurrent = () => epoch === null || currentEpoch() === epoch
   let phase = 'idle'
   let lastError = null
   let result = null
@@ -132,13 +139,18 @@ export function createEngine({ store, probe, heartbeat = null, bootId = 'boot',
     const work = workOf(current)
     const busy = TRANSIENT.has(phase)
     const workCount = liveWorkCount(work)
+    // A plan is an unfinished stop: the only way forward is to resume it, even when the stop left
+    // work behind. Preferring `pause` there used to trap a partial stop forever: every press
+    // re-ran the same stop, the residue could never be cancelled, and the button never offered the
+    // resume that would have released the plan.
     let action = 'none'
     if (busy) action = 'busy'
-    else if (current.readable === true && workCount > 0) action = 'pause'
     else if (plan !== null) action = 'resume'
-    const attention = plan !== null
-      ? (Array.isArray(plan.attention) ? plan.attention.length : 0)
-      : (Array.isArray(result?.attention) ? result.attention.length : 0)
+    else if (current.readable === true && workCount > 0) action = 'pause'
+    const attentionRows = plan !== null ? plan.attention : result?.attention
+    const attention = Array.isArray(attentionRows) ? attentionRows.length : 0
+    const first = attention > 0 ? attentionRows[0] : null
+    const focus = first === null ? null : (typeof first === 'string' ? first : (first.id || first.detail || null))
     return {
       phase,
       action,
@@ -153,15 +165,21 @@ export function createEngine({ store, probe, heartbeat = null, bootId = 'boot',
         jobs: current.jobs.length,
       },
       attention,
+      focus, // ui-copy-ignore
       error: lastError ?? (plan?.status === 'pausing' ? 'pause-interrupted' : plan?.status === 'partial' ? 'pause-partial' : null), // ui-copy-ignore
       result,
     }
   }
 
   function freshSession(session) {
+    // A session in the captured live set had its turn open, so the press owns a continuation for it.
+    // A crash row is different: it is evidence that a turn was open, not permission to send text.
+    const running = session.running === true
     return {
       sessionId: session.sessionId,
-      running: session.running === true,
+      running,
+      intent: running && session.intent !== 'mount' ? 'continue' : 'mount',
+      epoch: running && Number.isSafeInteger(session.epoch) ? session.epoch : 0,
       lastTurn: Number.isSafeInteger(session.lastTurn) ? session.lastTurn : null,
     }
   }
@@ -183,7 +201,13 @@ export function createEngine({ store, probe, heartbeat = null, bootId = 'boot',
       if (existing !== undefined) {
         // Stopping again refreshes the baseline; a plain union would keep a stale turn number.
         if (Number.isSafeInteger(row.lastTurn)) existing.lastTurn = row.lastTurn
-        if (row.running === false) existing.running = false
+        // A new capture of an actually-running session upgrades a crash-only row: the person then
+        // pressed pause while it was running, which is an explicit request to continue it later.
+        if (row.intent === 'continue' || row.running === true) {
+          existing.intent = 'continue'
+          existing.running = true
+        }
+        if (Number.isSafeInteger(row.epoch) && row.epoch > 0) existing.epoch = row.epoch
         continue
       }
       const copy = { ...row }
@@ -206,6 +230,10 @@ export function createEngine({ store, probe, heartbeat = null, bootId = 'boot',
   }
 
   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
@@ -245,7 +273,19 @@ export function createEngine({ store, probe, heartbeat = null, bootId = 'boot',
         attention: [], // ui-copy-ignore
       }
       : { ...basePlan, status: 'pausing', attention: Array.isArray(basePlan.attention) ? basePlan.attention : [] }
+    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))
+    plan.sessions = plan.sessions.map((row) => {
+      if (row.intent !== 'continue') 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
+      // A new pause cycle after a restore attempt needs a new request id: the previous one was
+      // already admitted, and the official prompt dedupe would silently swallow the new message.
+      // Retrying the same pause (no restore attempt yet) keeps the id, so admission stays idempotent.
+      return { ...row, epoch: restoredBefore && priorEpoch >= 1 ? priorEpoch + 1 : Math.max(priorEpoch, 1) }
+    })
     plan.goals = unionById(plan.goals ?? [], work.goals.map(freshGoal), (goal) => `${goal?.sessionId}:${goal?.goalId}`)
     plan.jobs = unionById(plan.jobs ?? [], work.jobs.map(freshJob), (job) => job?.id)
     if (persist(plan) === null) {
@@ -262,6 +302,12 @@ export function createEngine({ store, probe, heartbeat = null, bootId = 'boot',
       log(`stopping work failed: ${error?.message ?? error}`)
       stopped = { canceled: [], unknown: [], pausedGoals: [], goalErrors: [], killedJobs: [], jobErrors: [], stillRunning: [], sessions: [] }
     }
+    if (isCurrent() === false) {
+      // A reload happened while this press was awaiting the stop. The new instance owns the plan
+      // now; writing here would erase whatever it captured in the meantime.
+      log('stale instance: pause result discarded')
+      return { status: 'failed', reason: 'reloaded' }
+    }
 
     // A cancelled turn bumps the agent's turn counter, so the baseline is read after the stop.
     // Without this a restore would mistake its own cancelled turn for work the person continued.
@@ -279,7 +325,10 @@ export function createEngine({ store, probe, heartbeat = null, bootId = 'boot',
     const keptGoals = (plan.goals ?? []).filter((goal) => !(stopped.pausedGoals ?? []).some((row) => row.sessionId === goal.sessionId && row.goalId === goal.goalId))
     plan.goals = [...keptGoals, ...pausedGoals]
     const stillRunning = stopped.stillRunning ?? []
-    plan.status = stillRunning.length > 0 ? 'partial' : 'paused'
+    // A session poll alone is not proof the stop was clean: a goal whose pause threw and a job whose
+    // kill threw are still live work, and reporting `paused` there hid exactly what needs a person.
+    const incomplete = stillRunning.length + (stopped.goalErrors ?? []).length + (stopped.jobErrors ?? []).length
+    plan.status = incomplete > 0 ? 'partial' : 'paused'
     plan.stoppedAt = new Date(now()).toISOString()
     plan.stopped = {
       canceled: stopped.canceled ?? [],
@@ -289,11 +338,19 @@ export function createEngine({ store, probe, heartbeat = null, bootId = 'boot',
       killedJobs: stopped.killedJobs ?? [],
       jobErrors: stopped.jobErrors ?? [],
     }
+    const errorId = (kind, detail) => {
+      const match = new RegExp(`^${kind} ([^:]+):`).exec(String(detail))
+      return match === null ? '' : match[1].trim()
+    }
     plan.attention = [
       ...(Array.isArray(basePlan?.attention) ? basePlan.attention : []),
       ...stillRunning.map((id) => ({ kind: 'session', id, detail: 'still running' })),
-      ...(stopped.goalErrors ?? []).map((detail) => ({ kind: 'goal', id: '', detail })),
-      ...(stopped.jobErrors ?? []).map((detail) => ({ kind: 'job', id: '', detail })),
+      ...(stopped.goalErrors ?? []).map((detail) => {
+        const goalId = errorId('goal', detail)
+        const owner = [...(basePlan?.goals ?? []), ...(current.goals ?? [])].find((row) => row.goalId === goalId)
+        return { kind: 'goal', id: owner?.sessionId ?? goalId, detail }
+      }),
+      ...(stopped.jobErrors ?? []).map((detail) => ({ kind: 'job', id: errorId('job', detail), detail })),
     ]
     if (isCrashPlan(basePlan) === true) {
       // The crash record described work that was not paused. This press did pause it, so the plan
@@ -361,19 +418,29 @@ export function createEngine({ store, probe, heartbeat = null, bootId = 'boot',
       const status = typeof outcome?.status === 'string' ? outcome.status : 'failed'
       if (TERMINAL.has(status) === false) {
         summary.failed.push(`${label}: ${outcome?.detail ?? 'unknown'}`)
-        return
+        return outcome
       }
       record(key, status)
       if (status === 'restored') summary.restored.push(label)
       else if (status === 'skipped') summary.skipped.push(label)
       else summary.attention.push(`${label}: ${outcome?.detail ?? 'needs a look'}`)
+      return outcome
     }
 
     for (const session of plan.sessions ?? []) {
       await step(`s:${session.sessionId}`, `session ${session.sessionId}`, () => probe.restoreSession(session, { plan }))
     }
     for (const goal of plan.goals ?? []) {
-      await step(`g:${goal.sessionId}:${goal.goalId ?? ''}`, `goal ${goal.goalId ?? goal.sessionId}`, () => probe.restoreGoal(goal, { plan }))
+      const key = `g:${goal.sessionId}:${goal.goalId ?? ''}`
+      const outcome = await step(key, `goal ${goal.goalId ?? goal.sessionId}`, () => probe.restoreGoal(goal, { plan }))
+      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'
+      }
     }
     // 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.
@@ -401,6 +468,10 @@ 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) {
@@ -470,27 +541,74 @@ export function createEngine({ store, probe, heartbeat = null, bootId = 'boot',
    */
   async function hydrate(options = {}) {
     crashFallback = null
+    lastError = null
     const residue = options?.residue ?? heartbeat?.residue ?? null
-    if (residue !== null && residue !== undefined && pausedPlan() === null && crashPlan() === null) {
-      let plan = null
+    const restored = typeof store.lastRestore === 'function' ? store.lastRestore() : null
+    result = restored !== null && typeof restored === 'object' ? (restored.summary ?? null) : null
+    let durable = true
+
+    if (residue !== null && residue !== undefined) {
+      let crash = null
       try {
-        plan = probe.crashPlan(residue, { planId: `crash-${Number.isFinite(residue.at) ? residue.at : 0}-${Array.isArray(residue.sessions) ? residue.sessions.length : 0}` })
+        crash = probe.crashPlan(residue, {
+          planId: `crash-${Number.isFinite(residue.at) ? residue.at : 0}-${Array.isArray(residue.sessions) ? residue.sessions.length : 0}`,
+        })
       } catch (error) {
         log(`cannot derive crash plan: ${error?.message ?? error}`)
       }
-      if (plan !== null) {
-        const stored = typeof store.writePending === 'function' ? store.writePending(plan) : null
-        // A failed write keeps the plan in memory so this process can still restore it; only the
-        // next restart loses it.
-        crashFallback = stored ?? plan
-        log('crash plan recorded')
+      if (crash !== null) {
+        const existing = pausedPlan() ?? crashPlan()
+        if (existing === null) {
+          const stored = typeof store.writePending === 'function' ? store.writePending(crash) : null
+          // 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
+            durable = false
+            lastError = 'store'
+            heartbeat?.hold?.()
+            log('cannot record the crash plan; keeping the previous heartbeat')
+          } else {
+            log('crash plan recorded')
+          }
+        } else {
+          // A plan from an earlier pause outranks the crash record, but it must not hide it: every
+          // session the crash residue names is merged in as mount-only work. Otherwise a crash that
+          // happened after a partial restore would silently drop sessions the next press captured.
+          const known = new Set((existing.sessions ?? []).map((row) => row?.sessionId))
+          const added = crash.sessions
+            .filter((row) => known.has(row.sessionId) === false)
+            .map((row) => ({ sessionId: row.sessionId, intent: 'mount', epoch: 0, running: false, lastTurn: null, crash: true }))
+          if (added.length > 0) {
+            const plan = {
+              ...existing,
+              sessions: [...(existing.sessions ?? []), ...added],
+              crashes: (Number.isSafeInteger(existing.crashes) ? existing.crashes : 0) + added.length,
+              attention: [
+                ...(Array.isArray(existing.attention) ? existing.attention : []),
+                ...added.map((row) => ({ kind: 'session', id: row.sessionId, detail: 'crashed: mounted only' })),
+              ],
+            }
+            const isCrash = isCrashPlan(plan)
+            const stored = isCrash
+              ? (typeof store.writePending === 'function' ? store.writePending(plan) : null)
+              : store.write(plan)
+            if (stored === null) {
+              durable = false
+              lastError = 'store'
+              if (isCrash) crashFallback = plan
+              heartbeat?.hold?.()
+              log('cannot merge the crash plan; keeping the previous heartbeat')
+            } else {
+              log(`crash sessions merged (${added.length})`)
+            }
+          }
+        }
       }
     }
-    const restored = typeof store.lastRestore === 'function' ? store.lastRestore() : null
-    result = restored !== null && typeof restored === 'object' ? (restored.summary ?? null) : null
+
     phase = pausedPlan() !== null ? 'paused' : 'idle'
-    lastError = null
-    return phase
+    return { phase, durable }
   }
 
   return {

package/lib/epoch.js

@@ -0,0 +1,27 @@
+/**
+ * One epoch per plugin instance, shared across HMR module evaluations.
+ *
+ * A reload can leave the previous engine's press mid-await. Without a generation marker that old
+ * press must not overwrite the plan the new instance wrote. The marker lives on `globalThis`, so a
+ * re-evaluated module sees the same counter, and every write checks it.
+ */
+
+const KEY = Symbol.for('dsh-pause-resume.epoch')
+
+export function nextEpoch() {
+  const holder = globalThis
+  const value = Number.isSafeInteger(holder[KEY]) ? holder[KEY] : 0
+  holder[KEY] = value + 1
+  return holder[KEY]
+}
+
+export function currentEpoch() {
+  const value = globalThis[KEY]
+  return Number.isSafeInteger(value) ? value : 0
+}
+
+/** A disposed instance invalidates its own epoch, so its in-flight writes become no-ops. */
+export function dropEpoch(epoch) {
+  if (currentEpoch() !== epoch) return
+  nextEpoch()
+}

package/lib/heartbeat.js

@@ -34,6 +34,8 @@ export function createHeartbeat({ dir, bootId, intervalMs = 5000, listRunning, n
   let stopped = false
   let pending = []
   let lastWritten = ''
+  /** A boot whose crash residue could not be recorded must not overwrite the previous heartbeat. */
+  let writable = true
 
   function noteError(message) {
     try {
@@ -149,6 +151,7 @@ export function createHeartbeat({ dir, bootId, intervalMs = 5000, listRunning, n
   }
 
   function writePending() {
+    if (writable === false) return false
     return dirty() ? persist(pending) : true
   }
 
@@ -225,8 +228,15 @@ export function createHeartbeat({ dir, bootId, intervalMs = 5000, listRunning, n
     }
   }
 
+  /** Freeze the file after a failed crash-plan write: it is the only remaining copy of that work. */
+  function hold() {
+    writable = false
+    stop()
+  }
+
   /** The residue was restored: from here on the heartbeat describes this process again. */
   function release() {
+    writable = true
     residue = null
     void refresh(true)
   }
@@ -236,6 +246,7 @@ export function createHeartbeat({ dir, bootId, intervalMs = 5000, listRunning, n
     peek,
     start,
     stop,
+    hold,
     release,
     flush,
     get residue() {

package/lib/probe.js

@@ -232,10 +232,14 @@ export function createProbe(services, options = {}) {
   }
 
   /** The continuation message: a real user message, so the session history shows why it moved. */
-  function continuation(plan, sessionId) {
+  function continuation(plan, sessionId, epoch) {
+    // 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
     return {
       sessionId,
-      requestId: `${plan.planId}:continue:${sessionId}`,
+      requestId: `${plan.planId}:continue:${sessionId}:${cycle}`,
       content: [{ type: 'text', text: continueText }],
       // `queue` is the shipped public mode: deliver after the current turn, start one when idle.
       mode: 'queue',
@@ -275,24 +279,40 @@ export function createProbe(services, options = {}) {
       try {
         agent = await mount(sessionId)
       } catch (error) {
-        return { status: 'failed', detail: String(error?.message ?? error).slice(0, 120) }
+        const detail = String(error?.message ?? error).slice(0, 120)
+        // A subagent row belongs to the parent chat that owns its routing; this process may not
+        // claim it directly, and a retry would fail the same way forever. The parent restores it.
+        if (/owned by subagent routing/i.test(detail)) {
+          return { status: 'attention', detail: 'subagent session; its parent restores it' }
+        }
+        return { status: 'failed', detail }
       }
     }
 
-    if (session.running !== true) return { status: 'restored', detail: mounted ? 'mounted' : 'attached', continued: false }
+    // 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.
+    const intent = session.intent === undefined && session.running === true ? 'continue' : session.intent
+    if (intent !== 'continue') {
+      return { status: 'restored', detail: mounted ? 'mounted' : 'attached', continued: false }
+    }
 
-    // Someone continued by hand after the pause: the press must not add a second turn.
+    // A turn that is already open is not evidence the continuation arrived, but it is work in
+    // progress: starting a second one would be a duplicate. A turn that advanced and then ended is
+    // different: it may have been the continuation, or it may have been interrupted after the
+    // request was admitted. Neither case allows resending, and neither may be reported as a clean
+    // `skipped` with no attention.
     const baseline = Number.isSafeInteger(session.lastTurn) ? session.lastTurn : null
     const turnBefore = lastTurnOf(agent)
-    if (agent.status === 'running' || (baseline !== null && turnBefore !== null && turnBefore > baseline)) {
-      return { status: 'skipped', detail: 'already continued', continued: false }
+    if (agent.status === 'running') return { status: 'skipped', detail: 'already running', continued: false }
+    if (baseline !== null && turnBefore !== null && turnBefore > baseline) {
+      return { status: 'attention', detail: 'turn advanced after the pause; not sent again', continued: false }
     }
 
     const controller = service(services, 'sessionController')
     if (controller === undefined || controller === null || typeof controller.prompt !== 'function') {
       return { status: 'failed', detail: 'prompt unavailable', continued: false }
     }
-    const request = continuation(plan, sessionId)
+    const request = continuation(plan, sessionId, session.epoch)
     try {
       // Two arguments: the shipped service takes the caller's AbortSignal. Passing source metadata
       // here made every restore fail on a live Harness while the fake in the tests accepted it.
@@ -344,12 +364,21 @@ export function createProbe(services, options = {}) {
     if (view === undefined || (typeof goal.goalId === 'string' && view.id !== goal.goalId)) {
       return { status: 'skipped', detail: 'goal is gone' }
     }
-    // A goal that is already active and armed was restored by an earlier press, or re-armed by the
-    // person: it must not be touched again. A disarmed active goal is not ours to arm either.
+    // An active goal is normally not ours to touch. The one exception is a goal this same plan
+    // armed in an earlier process: activation is per-process, so a restart leaves it `disarmed` at
+    // exactly the revision the plan recorded. Another person's goal has no such record.
     if (view.phase === 'active') {
-      return view.activation === 'armed'
-        ? { status: 'skipped', detail: 'already active' }
-        : { status: 'skipped', detail: 'goal disarmed' }
+      if (view.activation === 'armed') return { status: 'skipped', detail: 'already active' }
+      if (Number.isSafeInteger(goal.armedRevision) && goal.armedRevision === view.revision) {
+        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)
+        return { status: 'restored', detail: 're-armed after restart', revision: after?.revision ?? null }
+      }
+      return { status: 'skipped', detail: 'goal disarmed' }
     }
     if (view.phase !== 'paused') return { status: 'skipped', detail: `goal is ${view.phase}` }
     // The saved revision is the person's veto: a goal edited after the pause is not ours to resume.
@@ -366,7 +395,8 @@ export function createProbe(services, options = {}) {
     } catch (error) {
       return { status: 'failed', detail: String(error?.message ?? error).slice(0, 120) }
     }
-    return { status: 'restored', detail: 'armed' }
+    const after = goalView(services, agent)
+    return { status: 'restored', detail: 'armed', revision: after?.revision ?? null }
   }
 
   /**
@@ -379,7 +409,7 @@ export function createProbe(services, options = {}) {
     const rows = Array.isArray(residue.sessions) ? residue.sessions : []
     const sessions = rows
       .filter((row) => typeof row?.sessionId === 'string')
-      .map((row) => ({ sessionId: row.sessionId, running: false, lastTurn: null, crash: true }))
+      .map((row) => ({ sessionId: row.sessionId, intent: 'mount', epoch: 0, running: false, lastTurn: null, crash: true }))
     if (sessions.length === 0) return null
     return {
       version: 3, // ui-copy-ignore

package/lib/snapshot.js

@@ -144,6 +144,24 @@ export function createStore(dir, options = {}) {
     if (typeof plan.planId !== 'string' || plan.planId === '') plan.planId = `plan-${plan.createdAt ?? stamp}`
     if (Array.isArray(plan.attention) === false) plan.attention = []
     if (plan.status === 'pausing') plan.interrupted = true
+    // `running` used to mean two different things: "this press stopped a turn here" (continue on
+    // resume) and "this session is merely in the plan" (mount only). Version 3 records the intent
+    // explicitly so a crash-only row can never turn into a continuation by accident.
+    plan.sessions = (Array.isArray(plan.sessions) ? plan.sessions : []).map((row) => {
+      if (typeof row?.sessionId !== 'string') return row
+      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)
+      return { ...row, intent, epoch, running: intent === 'continue' }
+    })
+    plan.goals = (Array.isArray(plan.goals) ? plan.goals : []).map((row) => (
+      row !== null && typeof row === 'object' && Number.isSafeInteger(row.armedRevision) === false
+        ? { ...row, armedRevision: null }
+        : row
+    ))
     return plan
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-pause-resume",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "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",
@@ -18,6 +18,7 @@
     "locale/*.json",
     "icon.svg",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "keywords": [