dsh-pause-resume 0.2.0 → 0.3.0

package/README.md

@@ -40,15 +40,19 @@ A restore is not a claim that work continued. It is three honest steps per item:
 3. **Re-arm a goal** with the revision it had when paused. The revision is the person's veto: if the
    goal changed while paused, it is not ours to resume and the item is `skipped`.
 
-Every finished item is journaled before the plan is archived, so a crash in the middle of a restore
-continues with the remainder instead of restoring the same session twice. A failure leaves the plan
-and the journal on disk: the next press retries only the failed item.
+Every attempt is journaled with the id of the process that made it, but a journal is reporting, not a
+promise: the next boot asks the live Harness again instead of trusting an old row. The continuation
+request id is derived from the plan and the session, so a retry before a turn starts is deduplicated
+by the Host. A failure leaves the plan on disk and the next press retries every item that still needs
+work.
 
 ## Crash, not just a press
 
 A press writes a snapshot. A crash writes nothing, so the plugin keeps a heartbeat instead:
 `running.json` holds the sessions whose turn is open right now and the id of the process that wrote
-it. A new process finds the previous process's record and offers ▶ with no press needed.
+it. The previous process's record is turned into a crash plan in `pending.json` before the heartbeat
+file is replaced, so a second or third restart still sees the same work and offers ▶ with no press
+needed.
 
 A crash record is deliberately weaker than a press: it proves a turn was open, not whether the person
 wanted it continued. So restore mounts those sessions and lists them in the outcome; it does not
@@ -74,8 +78,8 @@ machine; local-only is the default.
   a double press and a tool call cannot overlap. The second caller is told `busy`.
 * **Durable before destructive.** No turn is cancelled until the plan is on disk. A failed write means
   nothing was stopped.
-* **Idempotent.** A restore journals every finished item; the continuation request id is derived from
-  the plan, so a retry cannot post the same message twice.
+* **Idempotent.** The continuation request id is derived from the plan and the session, so a retry
+  cannot post the same message twice; a turn that already moved is not continued again.
 * **Honest.** Unreadable state never reports `paused`. A session deleted by hand, a goal changed by
   hand, a session already running: each is skipped and named in the outcome.
 * **No hidden takeover.** There is no public API to detach an agent, so the pause guarantee is
@@ -92,7 +96,8 @@ All state lives under `$DSH_HOME/pause-resume/`:
 | File | Purpose |
 | --- | --- |
 | `snapshot.json` | the work a press stopped, `pausing` or `paused` |
-| `journal/<planId>.jsonl` | restore items already finished |
+| `pending.json` | a crash plan, kept until a restore finishes |
+| `journal/<planId>.jsonl` | restore attempts, tagged with the boot that made them |
 | `restores/<planId>.json` | the archived plan, kept as a record of the last restore |
 | `last-restore.json` | summary of the last restore |
 | `running.json` | sessions with an open turn, for crash residue |

package/client.js

@@ -172,24 +172,36 @@ window.__ModuleLoader__.load({
         ensureStyle()
         mounted.current = true
         let timer = null
+        let stopped = false
         let current = null
-        const beat = () => {
-          if (document.visibilityState !== 'visible' || inflight.current !== null) return
-          try {
-            current?.abort()
-          } catch {}
+        // One request at a time, and the next one starts after this one settles. A fixed interval
+        // that aborts its own predecessor made any answer slower than the interval invisible.
+        const beat = async () => {
+          timer = null
+          if (stopped || document.visibilityState !== 'visible' || inflight.current !== null) { schedule() ; return }
           current = typeof AbortController === 'function' ? new AbortController() : null
-          void pull(current?.signal)
+          try {
+            await pull(current?.signal)
+          } finally {
+            current = null
+            schedule()
+          }
+        }
+        const schedule = () => {
+          if (stopped || timer !== null) return
+          timer = setTimeout(() => { void beat() }, POLL_MS)
         }
-        beat()
-        timer = setInterval(beat, POLL_MS)
         const onVisible = () => {
-          if (document.visibilityState === 'visible') beat()
+          if (document.visibilityState !== 'visible') return
+          if (timer !== null) { clearTimeout(timer); timer = null }
+          void beat()
         }
+        void beat()
         document.addEventListener('visibilitychange', onVisible)
         return () => {
+          stopped = true
           mounted.current = false
-          if (timer !== null) clearInterval(timer)
+          if (timer !== null) clearTimeout(timer)
           try {
             current?.abort()
           } catch {}

package/index.js

@@ -6,7 +6,7 @@ import { createHeartbeat } from './lib/heartbeat.js'
 import { createProbe, listRunning } from './lib/probe.js'
 
 export const name = 'dsh-pause-resume'
-export const VERSION = '0.2.0'
+export const VERSION = '0.3.0'
 
 const BASE_PATH = '/dsh-pause-resume'
 const BUTTON_HEADER = 'x-dsh-pause-resume'
@@ -147,7 +147,7 @@ function serve(ctx, engine, heartbeat, options) {
       route(async (req, res) => {
         const outcome = await engine.pause()
         log(`pause: ${outcome.status}${outcome.status === 'busy' ? ` (${outcome.phase})` : ''}`)
-        if (outcome.status === 'paused') heartbeat.release()
+        if (outcome.status === 'paused' || outcome.status === 'partial') heartbeat.release()
         sendJson(res, 200, { ...engine.describe(), outcome })
       }, false),
     ],
@@ -216,6 +216,7 @@ export function apply(ctx, config = {}) {
     store,
     probe,
     heartbeat,
+    bootId: bootId(),
     graceMs: Number.isFinite(config?.graceMs) ? config.graceMs : 2000,
     log,
   })
@@ -265,11 +266,12 @@ export function apply(ctx, config = {}) {
 
   void (async () => {
     try {
-      // The heartbeat claims the previous process's record in `start`, and the engine's crash plan
-      // is derived from that claim: start first, or the residue is read as absent and lost.
-      heartbeat.start()
+      // 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 })
       if (disposed) return
-      await engine.hydrate()
+      heartbeat.start()
       if (disposed) return
       const dispose = serve(ctx, engine, heartbeat, { allowRemote })
       if (disposed) dispose()

package/lib/engine.js

@@ -6,26 +6,34 @@
  * set, so two windows, a double press and a tool call can never overlap. The client is not allowed
  * to infer a phase: it asks, and renders the answer.
  *
- * A plan is kept until every item in it has a terminal outcome. A restore that could not put one
- * session back keeps the plan and the journal, so the next press retries exactly the missing item
- * instead of replaying the whole pause.
+ * `action` is state-derived, never phase-derived. Live work asks for a pause; a plan with no live
+ * work asks for a resume; neither is `none`. That single rule is what makes a second press useful
+ * after a failed pause, a partial stop, or a restart: the button does what the Harness still needs,
+ * not what the last operation intended.
  *
- * The engine performs no I/O of its own. `store` persists, `probe` reads and acts on the running
- * Harness, so every transition here is testable without a Harness.
+ * A plan is kept until every item in it has a terminal outcome or a retryable failure. Attention
+ * outcomes (a continuation that was admitted but never opened a turn, a job that cannot be
+ * replayed) are terminal: they are carried into the last-restore record and shown as a dot, but
+ * they never cause the same message to be delivered twice. The crash plan is written to disk
+ * before the heartbeat overwrites the previous process's record, so a second or third restart
+ * still sees the same pending work.
  */
 
 const TRANSIENT = new Set(['pausing', 'resuming'])
 const TERMINAL = new Set(['restored', 'skipped', 'attention'])
 
-export function createEngine({ store, probe, heartbeat = null, now = () => Date.now(), graceMs = 2000, log = () => {} }) {
+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 = () => {} }) {
   let phase = 'idle'
   let lastError = null
   let result = null
   /** Set while a press runs, so a second caller joins the answer instead of starting work again. */
   let inflight = null
-  /** The crash plan is derived once per boot: its id must not move between two polls. */
-  let crash = null
-  let crashRead = false
+  /** Crash plan kept in memory only when its durable write failed; a reload loses it, the file does not. */
+  let crashFallback = null
   let counter = 0
 
   function newPlanId(kind) {
@@ -33,29 +41,22 @@ export function createEngine({ store, probe, heartbeat = null, now = () => Date.
     return `${kind}-${now().toString(36)}-${counter.toString(36)}`
   }
 
-  function pendingPlan() {
+  function pausedPlan() {
     return store.read()
   }
 
-  function readCrash() {
-    if (crashRead) return crash
-    crashRead = true
-    try {
-      const residue = heartbeat?.residue ?? null
-      // The id is derived from the residue itself: two polls of the same crash share one journal,
-      // and a different crash gets its own.
-      const at = Number.isFinite(residue?.at) ? residue.at : 0
-      const count = Array.isArray(residue?.sessions) ? residue.sessions.length : 0
-      crash = probe.crashPlan(residue, { planId: `crash-${at}-${count}` })
-    } catch (error) {
-      log(`cannot read crash residue: ${error?.message ?? error}`)
-      crash = null
-    }
-    return crash
+  function crashPlan() {
+    const stored = typeof store.readPending === 'function' ? store.readPending() : null
+    return stored ?? crashFallback
   }
 
+  /** Exactly one plan is pending, and a finished pause outranks a leftover crash record. */
   function currentPlan() {
-    return pendingPlan() ?? readCrash()
+    return pausedPlan() ?? crashPlan()
+  }
+
+  function isCrashPlan(plan) {
+    return plan !== null && plan !== undefined && plan.source === 'crash'
   }
 
   function itemKeys(plan) {
@@ -66,10 +67,17 @@ export function createEngine({ store, probe, heartbeat = null, now = () => Date.
     return keys
   }
 
+  /**
+   * Rows written by an earlier process are evidence, not permission to skip: a new process must
+   * check the live Harness again. Only this boot's rows reduce what is still outstanding.
+   */
   function outstandingOf(plan) {
     if (plan === null || plan === undefined) return 0
-    const done = store.readJournal(plan.planId)
-    return itemKeys(plan).filter((key) => !done.has(key)).length
+    const rows = store.readJournal(plan.planId)
+    return itemKeys(plan).filter((key) => {
+      const row = rows.get(key)
+      return row === undefined || (row.boot !== null && row.boot !== bootId)
+    }).length
   }
 
   function countsOf(plan) {
@@ -83,14 +91,37 @@ export function createEngine({ store, probe, heartbeat = null, now = () => Date.
 
   function liveNow() {
     try {
-      const value = probe.live()
-      return value ?? { sessions: [], goals: [], jobs: [], readable: false, source: 'none' }
+      return probe.live() ?? emptyLive()
     } catch (error) {
       log(`cannot read live work: ${error?.message ?? error}`)
-      return { sessions: [], goals: [], jobs: [], readable: false, source: 'none' }
+      return emptyLive()
     }
   }
 
+  /**
+   * Only work that was actually stopped goes into the plan: a session whose turn was open, or a
+   * session that carries an armed goal. A session that ended normally is left alone, however it
+   * happens to look in the session list.
+   */
+  function workOf(current) {
+    const sessions = new Map()
+    for (const session of current.sessions ?? []) {
+      if (session.running === true) sessions.set(session.sessionId, session)
+    }
+    for (const goal of current.goals ?? []) {
+      if (!sessions.has(goal.sessionId)) sessions.set(goal.sessionId, { sessionId: goal.sessionId, running: false, lastTurn: null })
+    }
+    return {
+      sessions: [...sessions.values()],
+      goals: current.goals ?? [],
+      jobs: current.jobs ?? [], // ui-copy-ignore
+    }
+  }
+
+  function liveWorkCount(work) {
+    return work.sessions.length + work.goals.length + work.jobs.length
+  }
+
   /**
    * 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).
@@ -98,167 +129,229 @@ export function createEngine({ store, probe, heartbeat = null, now = () => Date.
   function describe() {
     const plan = currentPlan()
     const current = liveNow()
-    const busy = TRANSIENT.has(phase)
     const work = workOf(current)
-    const canPause = current.readable === true && work.sessions.length + work.goals.length + work.jobs.length > 0
-    const action = busy ? 'busy' : plan !== null ? 'resume' : canPause ? 'pause' : 'none'
-    const outstanding = outstandingOf(plan)
+    const busy = TRANSIENT.has(phase)
+    const workCount = liveWorkCount(work)
+    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)
     return {
       phase,
       action,
       source: plan === null ? null : plan.source ?? 'pause',
-      // A finished pause is complete even though every item still has to be restored later.
-      complete: plan === null ? null : plan.status === 'paused' && lastError === null,
-      outstanding: outstanding, // ui-copy-ignore
+      // `complete` means the stop finished and nothing is still turning. A partial stop is not.
+      complete: plan === null ? null : plan.status !== 'partial' && plan.status !== 'pausing' && lastError !== 'store',
+      outstanding: outstandingOf(plan), // ui-copy-ignore
       counts: countsOf(plan), // ui-copy-ignore
       live: { // ui-copy-ignore
         sessions: work.sessions.filter((session) => session.running === true).length,
         goals: current.goals.length,
         jobs: current.jobs.length,
       },
-      attention: Array.isArray(plan?.attention) ? plan.attention.length : 0, // ui-copy-ignore
-      error: lastError ?? (plan?.status === 'pausing' ? 'pause-interrupted' : null), // ui-copy-ignore
+      attention,
+      error: lastError ?? (plan?.status === 'pausing' ? 'pause-interrupted' : plan?.status === 'partial' ? 'pause-partial' : null), // ui-copy-ignore
       result,
     }
   }
 
-  /**
-   * Only work that was actually stopped goes into the plan: a session whose turn was open, or a
-   * session that carries an armed goal. A session that ended normally is left alone, however it
-   * happens to look in the session list.
-   */
-  function workOf(current) {
-    const sessions = new Map()
-    for (const session of current.sessions ?? []) {
-      if (session.running === true) sessions.set(session.sessionId, session)
+  function freshSession(session) {
+    return {
+      sessionId: session.sessionId,
+      running: session.running === true,
+      lastTurn: Number.isSafeInteger(session.lastTurn) ? session.lastTurn : null,
     }
-    for (const goal of current.goals ?? []) {
-      if (!sessions.has(goal.sessionId)) sessions.set(goal.sessionId, { sessionId: goal.sessionId, running: false, lastTurn: null })
+  }
+
+  function freshGoal(goal) {
+    return { sessionId: goal.sessionId, goalId: goal.goalId, revision: goal.revision }
+  }
+
+  function freshJob(job) {
+    return { id: job.id, owner: job.owner ?? null, status: job.status ?? null }
+  }
+
+  function unionSessions(base, additions) {
+    const out = []
+    const index = new Map()
+    for (const row of [...base, ...additions]) {
+      if (typeof row?.sessionId !== 'string') continue
+      const existing = index.get(row.sessionId)
+      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
+        continue
+      }
+      const copy = { ...row }
+      index.set(copy.sessionId, copy)
+      out.push(copy)
     }
-    return {
-      sessions: [...sessions.values()],
-      goals: current.goals ?? [],
-      jobs: current.jobs ?? [], // ui-copy-ignore
+    return out
+  }
+
+  function unionById(base, additions, idOf) {
+    const out = []
+    const seen = new Set()
+    for (const row of [...base, ...additions]) {
+      const id = idOf(row)
+      if (typeof id !== 'string' || id === '' || seen.has(id)) continue
+      seen.add(id)
+      out.push(row)
     }
+    return out
   }
 
-  function planOf(current, { planId, status }) {
-    return {
-      version: 2, // ui-copy-ignore
-      planId,
-      status,
-      source: 'pause', // ui-copy-ignore
-      createdAt: new Date(now()).toISOString(),
-      sessions: workOf(current).sessions.map((session) => ({
-        sessionId: session.sessionId,
-        running: session.running === true,
-        lastTurn: Number.isSafeInteger(session.lastTurn) ? session.lastTurn : null,
-      })),
-      goals: workOf(current).goals.map((goal) => ({
-        sessionId: goal.sessionId,
-        goalId: goal.goalId,
-        revision: goal.revision,
-      })),
-      jobs: workOf(current).jobs.map((job) => ({ id: job.id, owner: job.owner ?? null, status: job.status ?? null })),
+  function persist(plan) {
+    if (isCrashPlan(plan) === true) {
+      const stored = store.writePending(plan)
+      if (stored !== null) crashFallback = null
+      return stored
     }
+    return store.write(plan)
   }
 
-  async function runPause() {
+  /**
+   * Pause, including the second attempt after a partial stop. Capture happens before anything is
+   * stopped, and the plan is durable before the first cancellation, so a crash in between is
+   * visible as an interrupted pause instead of a clean one.
+   */
+  async function runPause(basePlan) {
     const current = liveNow()
+    const work = workOf(current)
     if (current.readable !== true) {
-      phase = 'idle'
+      phase = basePlan === null ? 'idle' : 'paused'
       lastError = 'registry'
       return { status: 'failed', reason: 'registry' }
     }
-    const work = workOf(current)
-    if (work.sessions.length + work.goals.length + work.jobs.length === 0) {
-      phase = 'idle'
-      return { status: 'idle', action: 'none' }
+    if (liveWorkCount(work) === 0) {
+      phase = basePlan === null ? 'idle' : 'paused'
+      return basePlan === null ? { status: 'idle', action: 'none' } : { status: 'already', phase }
     }
     lastError = null
-    // The plan exists before anything is stopped: a crash between the two is then visible as
-    // `pausing` on the next boot instead of being reported as a clean pause.
-    const draft = planOf(current, { planId: newPlanId('pause'), status: 'pausing' })
-    if (store.write(draft) === null) {
-      phase = 'idle'
+    const plan = basePlan === null
+      ? {
+        version: 3, // ui-copy-ignore
+        planId: newPlanId('pause'),
+        status: 'pausing', // ui-copy-ignore
+        source: 'pause', // ui-copy-ignore
+        createdAt: new Date(now()).toISOString(),
+        sessions: [], // ui-copy-ignore
+        goals: [], // ui-copy-ignore
+        jobs: [], // ui-copy-ignore
+        attention: [], // ui-copy-ignore
+      }
+      : { ...basePlan, status: 'pausing', attention: Array.isArray(basePlan.attention) ? basePlan.attention : [] }
+    plan.sessions = unionSessions(plan.sessions ?? [], work.sessions.map(freshSession))
+    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) {
+      // Nothing was stopped: the state is exactly what it was before the press.
+      phase = basePlan === null ? 'idle' : 'paused'
       lastError = 'store'
       return { status: 'failed', reason: 'store' }
     }
+
     let stopped = null
     try {
       stopped = await probe.stop(current, { graceMs })
     } catch (error) {
       log(`stopping work failed: ${error?.message ?? error}`)
-      stopped = { canceled: [], unknown: [], pausedGoals: [], goalErrors: [], killedJobs: [], jobErrors: [], stillRunning: [] }
+      stopped = { canceled: [], unknown: [], pausedGoals: [], goalErrors: [], killedJobs: [], jobErrors: [], stillRunning: [], sessions: [] }
     }
 
-    // Only goals that really stopped are part of the plan. Resuming a goal nobody paused would bump
-    // its revision for no reason and could override the person's own pause; a goal that failed to
-    // pause is reported instead and left alone.
-    // A cancelled turn bumps the agent's turn counter, so the baseline has to be read after the
-    // stop, not before it. Without this a restore would mistake its own cancelled turn for work
-    // the person continued by hand and skip the continuation it was asked to send.
+    // 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.
     const baseline = new Map((stopped.sessions ?? []).map((session) => [session.sessionId, session.lastTurn]))
-    draft.sessions = draft.sessions.map((session) => baseline.has(session.sessionId)
-      ? { ...session, lastTurn: Number.isSafeInteger(baseline.get(session.sessionId)) ? baseline.get(session.sessionId) : null }
+    plan.sessions = plan.sessions.map((session) => baseline.has(session.sessionId)
+      ? { ...session, lastTurn: Number.isSafeInteger(baseline.get(session.sessionId)) ? baseline.get(session.sessionId) : session.lastTurn }
       : session)
-    draft.goals = (stopped.pausedGoals ?? []).map((goal) => ({
+    // A goal that could not be paused is not in the plan: resuming it would bump a revision for no
+    // reason. It is reported instead, and the person can pause again after fixing whatever blocked it.
+    const pausedGoals = (stopped.pausedGoals ?? []).map((goal) => ({
       sessionId: goal.sessionId,
       goalId: goal.goalId,
       revision: goal.pausedRevision,
     }))
-    draft.status = 'paused'
-    draft.stoppedAt = new Date(now()).toISOString()
-    draft.stopped = {
+    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'
+    plan.stoppedAt = new Date(now()).toISOString()
+    plan.stopped = {
       canceled: stopped.canceled ?? [],
       unknown: stopped.unknown ?? [],
-      stillRunning: stopped.stillRunning ?? [],
+      stillRunning,
       goalErrors: stopped.goalErrors ?? [],
       killedJobs: stopped.killedJobs ?? [],
       jobErrors: stopped.jobErrors ?? [],
     }
-    draft.attention = [
-      ...(stopped.stillRunning ?? []).map((id) => ({ kind: 'session', id, detail: 'still running' })),
+    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 })),
     ]
-    if (store.write(draft) === null) {
-      // The durable copy still says `pausing`, which is the truth: the next boot reports it.
+    if (isCrashPlan(basePlan) === true) {
+      // 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)
+        if (kept === null) {
+          crashFallback = plan
+          lastError = 'store'
+        }
+      } 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.
       lastError = 'store'
     }
     phase = 'paused'
-    return { status: 'paused', counts: countsOf(draft), outstanding: outstandingOf(draft) }
+    return { status: plan.status === 'partial' ? 'partial' : 'paused', counts: countsOf(plan), outstanding: outstandingOf(plan) }
   }
 
-  function summaryOf() {
-    return { restored: [], skipped: [], failed: [], attention: [], jobs: 0, at: new Date(now()).toISOString() }
+  function summaryOf(plan) {
+    return { planId: plan.planId, source: plan.source ?? 'pause', restored: [], skipped: [], failed: [], attention: [], jobs: 0, at: new Date(now()).toISOString() }
   }
 
   /**
-   * One restore pass. Every item that ends in a terminal outcome is journaled, so a later press
-   * only walks what is left. A retryable failure keeps the plan; a durable write failure keeps it
-   * too, because the archive is the record that the work came back.
+   * One restore pass. Items are not skipped from the journal: the live Harness decides whether a
+   * session is already back, which is the only answer that survives a second process, a manual
+   * resume, or a reload. A retryable failure keeps the plan; attention outcomes are terminal.
    */
   async function runResume(plan) {
     lastError = null
-    // A crash in the middle of a pause left a plan that never finished stopping. Its sessions were
-    // still turning when the process died, so mounting them is safe but continuing them is not: the
-    // person asked for silence, not another round.
+    // A crash in the middle of a pause left a plan that never finished stopping. Mounting is safe;
+    // continuing is not, because the person asked for silence and the turn may have died mid-way.
     if (plan.status === 'pausing') {
-      plan.source = 'interrupted'
+      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 }))
       plan.status = 'paused'
+      if (persist(plan) === null) {
+        phase = 'paused'
+        lastError = 'store'
+        return { status: 'partial', summary: null, outstanding: outstandingOf(plan) }
+      }
     }
-    const summary = summaryOf()
+    const summary = summaryOf(plan)
     summary.jobs = countsOf(plan).jobs
-    const done = store.readJournal(plan.planId)
-    const record = (key) => {
-      done.add(key)
-      store.appendJournal(plan.planId, key)
+    const record = (key, status) => {
+      if (store.appendJournal(plan.planId, key, status, bootId) === false) {
+        // Reporting only: the restore already happened, so this never blocks the plan. It does mean
+        // a later boot counts the item as outstanding and checks it again, which is safe.
+        log(`cannot journal ${key}`)
+      }
     }
     const step = async (key, label, run) => {
-      if (done.has(key)) return
       let outcome
       try {
         outcome = await run()
@@ -266,55 +359,60 @@ export function createEngine({ store, probe, heartbeat = null, now = () => Date.
         outcome = { status: 'failed', detail: String(error?.message ?? error).slice(0, 120) }
       }
       const status = typeof outcome?.status === 'string' ? outcome.status : 'failed'
-      if (TERMINAL.has(status)) {
-        record(key)
-        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'}`)
-          plan.attention = [...(plan.attention ?? []), { kind: 'session', id: label, detail: String(outcome?.detail ?? '') }]
-        }
-      } else {
+      if (TERMINAL.has(status) === false) {
         summary.failed.push(`${label}: ${outcome?.detail ?? 'unknown'}`)
+        return
       }
+      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'}`)
     }
 
     for (const session of plan.sessions ?? []) {
       await step(`s:${session.sessionId}`, `session ${session.sessionId}`, () => probe.restoreSession(session, { plan }))
     }
     for (const goal of plan.goals ?? []) {
-      const key = `g:${goal.sessionId}:${goal.goalId ?? ''}`
-      await step(key, `goal ${goal.goalId ?? goal.sessionId}`, () => probe.restoreGoal(goal, { plan }))
+      await step(`g:${goal.sessionId}:${goal.goalId ?? ''}`, `goal ${goal.goalId ?? goal.sessionId}`, () => probe.restoreGoal(goal, { 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 is not a retryable item and never blocks the plan.
+    // reported once and left to the person. It never blocks the plan and is never restarted.
     for (const job of plan.jobs ?? []) summary.attention.push(`job ${job.id}: stopped, not restarted`)
 
     result = summary
-    const failed = summary.failed.length > 0
-    const pending = itemKeys(plan).filter((key) => !done.has(key))
-    if (failed || pending.length > 0) {
+    if (summary.failed.length > 0) {
       plan.restore = { at: summary.at, attempts: (plan.restore?.attempts ?? 0) + 1, failed: summary.failed } // ui-copy-ignore
-      if (store.write(plan) === null) lastError = 'store'
+      if (persist(plan) === null) lastError = 'store'
       else lastError = 'restore-partial'
       phase = 'paused'
-      return { status: 'partial', summary, outstanding: pending.length }
+      return { status: 'partial', summary, outstanding: outstandingOf(plan) }
     }
 
-    const consumed = store.consume(plan, summary)
-    if (!consumed?.ok) {
-      lastError = 'store'
-      phase = 'paused'
-      return { status: 'partial', summary, outstanding: 0 }
-    }
-    store.clearJournal(plan.planId)
-    if (plan.source === 'crash') {
-      crash = null
+    if (isCrashPlan(plan) === true) {
+      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 (typeof store.clearPending !== 'function' || store.clearPending() === false) {
+        lastError = 'store'
+        phase = 'paused'
+        return { status: 'partial', summary, outstanding: 0 }
+      }
+      crashFallback = null
+      if (typeof store.clearJournal === 'function') store.clearJournal(plan.planId)
       try {
         heartbeat?.release?.()
       } catch (error) {
         log(`cannot release crash record: ${error?.message ?? error}`)
       }
+    } else {
+      const consumed = store.consume(plan, summary)
+      if (!consumed?.ok) {
+        lastError = 'store'
+        phase = 'paused'
+        return { status: 'partial', summary, outstanding: 0 }
+      }
     }
     phase = 'idle'
     return { status: 'resumed', summary }
@@ -329,7 +427,7 @@ export function createEngine({ store, probe, heartbeat = null, now = () => Date.
       } catch (error) {
         log(`${kind} failed: ${error?.message ?? error}`)
         lastError = 'internal'
-        phase = pendingPlan() === null ? 'idle' : 'paused'
+        phase = currentPlan() === null ? 'idle' : 'paused'
         return { status: 'failed', reason: 'internal' }
       } finally {
         inflight = null
@@ -341,11 +439,15 @@ export function createEngine({ store, probe, heartbeat = null, now = () => Date.
 
   async function pause() {
     if (TRANSIENT.has(phase) || inflight !== null) return { status: 'busy', phase }
-    if (pendingPlan() !== null) return { status: 'already', phase }
+    const plan = currentPlan()
+    if (plan !== null) {
+      const work = workOf(liveNow())
+      if (liveWorkCount(work) === 0) return { status: 'already', phase }
+    }
     // Set synchronously, before the first await: two windows pressing at once are then exclusive
     // in the same tick they were dispatched, not one microtask later.
     phase = 'pausing'
-    return once('pause', runPause)
+    return once('pause', () => runPause(plan))
   }
 
   async function resume() {
@@ -361,12 +463,33 @@ export function createEngine({ store, probe, heartbeat = null, now = () => Date.
     })
   }
 
-  /** A reload of this plugin must not invent a phase: the disk and the running Harness decide it. */
-  async function hydrate() {
-    crashRead = false
-    crash = null
-    readCrash()
-    phase = pendingPlan() !== null ? 'paused' : 'idle'
+  /**
+   * A reload or restart must not invent a phase: the disk and the running Harness decide it. The
+   * crash residue is handed in by the caller, because it has to be read before the heartbeat
+   * overwrites the previous process's file; it is persisted here so a second restart still sees it.
+   */
+  async function hydrate(options = {}) {
+    crashFallback = null
+    const residue = options?.residue ?? heartbeat?.residue ?? null
+    if (residue !== null && residue !== undefined && pausedPlan() === null && crashPlan() === null) {
+      let plan = null
+      try {
+        plan = 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')
+      }
+    }
+    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
   }
 
@@ -376,7 +499,7 @@ export function createEngine({ store, probe, heartbeat = null, now = () => Date.
     resume,
     hydrate,
     get phase() { return phase },
-    get pendingPlan() { return pendingPlan },
-    get crashPlan() { return readCrash },
+    get pendingPlan() { return currentPlan },
+    get crashPlan() { return crashPlan },
   }
 }

package/lib/heartbeat.js

@@ -66,10 +66,18 @@ export function createHeartbeat({ dir, bootId, intervalMs = 5000, listRunning, n
 
   /** Flush a directory entry, so the rename that just happened survives a power loss too. */ // ui-copy-ignore
   function syncDir(path) {
+    if (process.platform === 'win32') return // ui-copy-ignore
     let fd = null
     try {
       fd = fsImpl.openSync(path, 'r')
       fsImpl.fsyncSync(fd)
+    } catch (error) {
+      // Some filesystems refuse a directory fsync after a rename that already landed. The record is
+      // published either way; only the power-loss guarantee is weaker, so this is not a failure.
+      const code = error?.code
+      if (code !== 'EPERM' && code !== 'EACCES' && code !== 'ENOTSUP' && code !== 'EINVAL' && code !== 'ENOSYS' && code !== 'EBADF' && code !== 'EISDIR') {
+        noteError(`cannot flush ${path}: ${error?.message ?? error}`)
+      }
     } finally {
       if (fd !== null) closeQuietly(fsImpl, fd)
     }
@@ -112,10 +120,13 @@ export function createHeartbeat({ dir, bootId, intervalMs = 5000, listRunning, n
     }
   }
 
-  /** Claims the previous process's heartbeat exactly once, before this process overwrites it. */
-  function capture() {
-    if (captured) return residue
-    captured = true
+  /**
+   * Read the previous process's record without claiming it. The caller has to read this before
+   * `start()` overwrites the file, and turning it into a durable plan may take a moment: a read that
+   * also claimed would leave the very next read empty if that write failed.
+   */
+  function peek() {
+    if (residue !== null) return residue
     let parsed = null
     try {
       parsed = JSON.parse(fsImpl.readFileSync(file, 'utf8'))
@@ -130,6 +141,13 @@ export function createHeartbeat({ dir, bootId, intervalMs = 5000, listRunning, n
     return residue
   }
 
+  /** Claims the previous process's heartbeat exactly once, before this process overwrites it. */
+  function capture() {
+    if (captured) return residue
+    captured = true
+    return peek()
+  }
+
   function writePending() {
     return dirty() ? persist(pending) : true
   }
@@ -215,6 +233,7 @@ export function createHeartbeat({ dir, bootId, intervalMs = 5000, listRunning, n
 
   return {
     note,
+    peek,
     start,
     stop,
     release,

package/lib/probe.js

@@ -10,9 +10,13 @@
  * - `sessionController.cancel({ sessionId })` stops one turn and keeps the pending inbox.
  * - `sessionController.resolveAgent(sessionId)` is the public resume path: it mounts the recorded
  *   preset and model selection, unlike a raw `agents.resume`.
- * - `sessionController.prompt(...)` admits one real user message and wakes the agent. That is the
- *   only supported way to make a resumed session continue work, so a restore that must continue
- *   says so with a visible message instead of pretending the turn came back by itself.
+ * - `sessionController.prompt(request, signal)` admits one real user message after resuming the
+ *   session itself. The shipped service validates the AbortSignal before it does anything, so the
+ *   second argument is that signal, never the source metadata (the service builds the source).
+ *   That is the only supported way to make a resumed session continue work, so a restore that must
+ *   continue says so with a visible message instead of pretending the turn came back by itself.
+ * - `sessionController.resolveAgent(sessionId)` answers an already live Agent directly and wraps a
+ *   cold one as `{ agent }`, or `{ error }`; both shapes are handled here.
  * - `goals.pause` / `goals.resume` require the exact current revision, and every transition bumps
  *   it. The revision captured after pausing is the one a later resume must present.
  */
@@ -145,7 +149,11 @@ export function createProbe(services, options = {}) {
       const goal = goalView(services, agent)
       const owned = listJobs(services, [agent.id])
       sessions.push({ sessionId: agent.id, running: agent.status === 'running', lastTurn: lastTurnOf(agent) })
-      if (goal !== undefined && goal.phase === 'active') goals.push({ sessionId: agent.id, goalId: goal.id, revision: goal.revision })
+      // 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') {
+        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 })
     }
     const unique = new Map()
@@ -229,7 +237,8 @@ export function createProbe(services, options = {}) {
       sessionId,
       requestId: `${plan.planId}:continue:${sessionId}`,
       content: [{ type: 'text', text: continueText }],
-      mode: 'followup',
+      // `queue` is the shipped public mode: deliver after the current turn, start one when idle.
+      mode: 'queue',
     }
   }
 
@@ -237,7 +246,11 @@ export function createProbe(services, options = {}) {
   async function mount(sessionId) {
     const controller = service(services, 'sessionController')
     if (controller !== undefined && controller !== null && typeof controller.resolveAgent === 'function') {
-      const agent = await controller.resolveAgent(sessionId)
+      const resolved = await controller.resolveAgent(sessionId)
+      // The shipped service returns the Agent itself when it is already live, `{ agent }` after a
+      // cold resume, and `{ error }` when the resume failed. All three are official shapes.
+      if (resolved !== null && typeof resolved === 'object' && 'error' in resolved) throw resolved.error
+      const agent = resolved !== null && typeof resolved === 'object' && 'agent' in resolved ? resolved.agent : resolved
       if (agent === undefined || agent === null || typeof agent.id !== 'string') throw new Error('resume returned no agent')
       return agent
     }
@@ -269,8 +282,9 @@ export function createProbe(services, options = {}) {
     if (session.running !== true) return { status: 'restored', detail: mounted ? 'mounted' : 'attached', continued: false }
 
     // Someone continued by hand after the pause: the press must not add a second turn.
-    const lastTurn = lastTurnOf(agent)
-    if (agent.status === 'running' || (Number.isSafeInteger(session.lastTurn) && lastTurn !== null && lastTurn > session.lastTurn)) {
+    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 }
     }
 
@@ -280,11 +294,35 @@ export function createProbe(services, options = {}) {
     }
     const request = continuation(plan, sessionId)
     try {
-      await controller.prompt(request, { kind: 'user', rpcId: request.requestId }, new AbortController().signal)
+      // 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.
+      await controller.prompt(request, new AbortController().signal)
     } catch (error) {
       return { status: 'failed', detail: String(error?.message ?? error).slice(0, 120), continued: false }
     }
-    return { status: 'restored', detail: mounted ? 'continued' : 'resumed and continued', continued: true }
+
+    // Admission is not execution. The shipped prompt answers `{ accepted: true }` without waking a
+    // queue when the same request id was already admitted, so the press waits for the visible sign
+    // of a turn (running, or a newer lastTurn) before it calls this item restored.
+    const started = await waitForTurn(sessionId, baseline, options.settleMs)
+    if (started === true) return { status: 'restored', detail: mounted ? 'continued' : 'resumed and continued', continued: true }
+    return { status: 'attention', detail: 'continuation admitted, no turn started', continued: false }
+  }
+
+  /** Bounded poll for the visible sign that an admitted continuation actually opened a turn. */
+  async function waitForTurn(sessionId, baseline, settle) {
+    if (settle === 0) return false
+    const deadline = Date.now() + (Number.isFinite(settle) ? settle : 1200)
+    for (;;) {
+      const agent = agentOf(services, sessionId)
+      if (agent !== undefined) {
+        if (agent.status === 'running') return true
+        const turn = lastTurnOf(agent)
+        if (baseline !== null && turn !== null && turn > baseline) return true
+      }
+      if (Date.now() >= deadline) return false
+      await new Promise((resolve) => setTimeout(resolve, 60))
+    }
   }
 
   /** Re-arm one paused goal. The saved revision is the person's veto: a changed goal is not ours. */
@@ -298,25 +336,33 @@ export function createProbe(services, options = {}) {
         return { status: 'failed', detail: String(error?.message ?? error).slice(0, 120) }
       }
     }
-    const goals = service(services, 'goals')
-    if (goals === undefined || goals === null || typeof goals.get !== 'function') return { status: 'skipped', detail: 'goals unavailable' }
-    let view
-    try {
-      view = goals.get(agent)
-    } catch (error) {
-      return { status: 'failed', detail: String(error?.message ?? error).slice(0, 120) }
+    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)) {
+      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.
+    if (view.phase === 'active') {
+      return view.activation === 'armed'
+        ? { status: 'skipped', detail: 'already active' }
+        : { status: 'skipped', detail: 'goal disarmed' }
     }
-    if (view === undefined || view === null) return { status: 'skipped', detail: 'goal cleared' }
-    if (view.id !== goal.goalId) return { status: 'skipped', detail: 'another goal' }
-    if (view.phase === 'active' && view.activation === 'armed') return { status: 'restored', detail: 'already active' }
-    if (view.phase === 'complete' || view.phase === 'blocked') return { status: 'attention', detail: `goal is ${view.phase}` }
-    // The plan stores the revision observed after `pause`; older plans called it `pausedRevision`.
-    const expected = Number.isSafeInteger(goal.pausedRevision) ? goal.pausedRevision : goal.revision
-    if (view.phase === 'paused' && Number.isSafeInteger(expected) && view.revision !== expected) {
-      return { status: 'skipped', detail: 'goal changed by hand' }
+    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.
+    if (Number.isSafeInteger(goal.revision) && view.revision !== goal.revision) {
+      return { status: 'skipped', detail: 'goal changed' }
     }
+    // The plan stores the revision observed after `pause`; 0.3 plans keep it in `revision`, 0.2
+    // plans called it `pausedRevision`.
+    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' }
     try {
-      goals.resume(agent, { id: view.id, revision: view.revision })
+      services_goals.resume(agent, { id: view.id, revision: view.revision })
     } catch (error) {
       return { status: 'failed', detail: String(error?.message ?? error).slice(0, 120) }
     }
@@ -336,7 +382,7 @@ export function createProbe(services, options = {}) {
       .map((row) => ({ sessionId: row.sessionId, running: false, lastTurn: null, crash: true }))
     if (sessions.length === 0) return null
     return {
-      version: 2, // ui-copy-ignore
+      version: 3, // ui-copy-ignore
       planId: planId ?? `crash-${Date.now().toString(36)}`,
       status: 'paused', // ui-copy-ignore
       source: 'crash', // ui-copy-ignore
@@ -344,6 +390,7 @@ export function createProbe(services, options = {}) {
       sessions,
       goals: [], // ui-copy-ignore
       jobs: [], // ui-copy-ignore
+      attention: [], // ui-copy-ignore
       crashes: sessions.length, // ui-copy-ignore
     }
   }

package/lib/snapshot.js

@@ -2,16 +2,24 @@ import * as fs from 'node:fs'
 import { dirname, join } from 'node:path'
 
 /**
- * The durable half of the pause button: one plan file, a per-plan restore journal, one archive per
- * consumed plan, and the last restore record.
+ * The durable half of the pause button: the active plan, the crash plan a restart inherited, one
+ * restore journal, one archive per consumed plan, and the last restore record.
  *
- * Every write is temp file + fsync + rename + directory fsync, so a reader never sees half a plan
- * and a crash leaves the previous complete file in place. Nothing here throws: a disk that cannot
- * be written answers `null`, and the caller decides whether to stay in its current phase instead
- * of claiming a state it could not record.
+ * Every write is temp file + fsync + rename + best-effort directory fsync, so a reader never sees
+ * half a plan and a crash leaves the previous complete file in place. A directory fsync that the
+ * platform refuses (EPERM/ENOTSUP on some network and sandboxed filesystems) does not undo a
+ * rename that already happened: the record is published, only its power-loss guarantee is weaker.
+ * Nothing here throws: a disk that cannot be written answers `false`/`null`, and the caller
+ * decides whether to stay in its current phase instead of claiming a state it could not record.
+ *
+ * Formats read: version 3 (this release), version 2 (0.2.x), version 1 (0.1.x). A version 1 plan is
+ * migrated conservatively: it has no turn baseline, so its sessions are mounted and never sent a
+ * continuation message, and its goal rows carry no revision, so they are reported, not resumed.
  */
 
 const UNSAFE = /[^A-Za-z0-9._-]/gu
+const CURRENT_VERSION = 3
+const DIR_SYNC_CODES = new Set(['EPERM', 'EACCES', 'ENOTSUP', 'EINVAL', 'ENOSYS', 'EBADF', 'EISDIR'])
 
 let counter = 0
 
@@ -32,6 +40,7 @@ export function createStore(dir, options = {}) {
   const log = typeof options.log === 'function' ? options.log : () => {}
 
   const snapshotPath = join(dir, 'snapshot.json')
+  const pendingPath = join(dir, 'pending.json')
   const journalDir = join(dir, 'journal')
   const restoresDir = join(dir, 'restores')
   const lastRestorePath = join(dir, 'last-restore.json')
@@ -40,15 +49,20 @@ export function createStore(dir, options = {}) {
 
   /** Flush a directory entry, so the rename that just happened survives a power loss too. */ // ui-copy-ignore
   function syncDir(path) {
+    if (process.platform === 'win32') return // ui-copy-ignore
     let fd = null
     try {
       fd = fsv.openSync(path, 'r')
       fsv.fsyncSync(fd)
+    } catch (error) {
+      const code = error?.code
+      if (DIR_SYNC_CODES.has(code) === false) log(`cannot flush ${path}: ${error?.message ?? error}`)
     } finally {
       if (fd !== null) closeQuietly(fsv, fd)
     }
   }
 
+  /** `published` is the truth: the rename landed, so readers see the new record. */
   function atomicWrite(target, value) {
     let body = null
     try {
@@ -85,29 +99,106 @@ export function createStore(dir, options = {}) {
     }
   }
 
-  function read() {
+  function parse(path) {
     let parsed = null
     try {
-      parsed = JSON.parse(fsv.readFileSync(snapshotPath, 'utf8'))
+      parsed = JSON.parse(fsv.readFileSync(path, 'utf8'))
     } catch {
       return null
     }
     if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) return null
-    if (parsed.version !== 2) return null
-    if (parsed.status !== 'pausing' && parsed.status !== 'paused') return null
     return parsed
   }
 
+  /**
+   * A version 1 plan predates the turn baseline and the goal revision. Mounting is safe; claiming
+   * that a turn was interrupted is not, and resuming a goal without its revision is not either.
+   */
+  function migrateLegacy(legacy, stamp) {
+    const sessions = (Array.isArray(legacy.sessions) ? legacy.sessions : [])
+      .filter((row) => typeof row?.sessionId === 'string')
+      .map((row) => ({ sessionId: row.sessionId, running: false, lastTurn: null }))
+    const goals = (Array.isArray(legacy.goals) ? legacy.goals : [])
+      .filter((row) => typeof row?.sessionId === 'string')
+      .map((row) => ({ sessionId: row.sessionId, goalId: typeof row.goalId === 'string' ? row.goalId : null, revision: null }))
+    const jobs = (Array.isArray(legacy.jobs) ? legacy.jobs : []).map((row) => ({ id: String(row?.id ?? ''), owner: row?.owner ?? null }))
+    return {
+      planId: `legacy-${stamp}`, // ui-copy-ignore
+      status: 'paused', // ui-copy-ignore
+      source: 'legacy', // ui-copy-ignore
+      legacy: true, // ui-copy-ignore
+      createdAt: legacy.createdAt ?? stamp,
+      sessions,
+      goals,
+      jobs,
+      attention: ['legacy plan: sessions are mounted only; goals need a new pause'],
+    }
+  }
+
+  function normalize(parsed, stamp = now()) {
+    if (parsed === null) return null
+    if (parsed.version === 1) return migrateLegacy(parsed, typeof parsed.createdAt === 'number' ? parsed.createdAt : stamp)
+    if (parsed.version !== 2 && parsed.version !== CURRENT_VERSION) return null
+    if (parsed.status !== 'pausing' && parsed.status !== 'paused' && parsed.status !== 'partial') return null
+    const plan = { ...parsed, version: CURRENT_VERSION }
+    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
+    return plan
+  }
+
+  function readFrom(path) {
+    const parsed = parse(path)
+    if (parsed === null) return null
+    // A version 1 plan has no plan id; the file stamp keeps one journal per legacy press.
+    let stamp = now()
+    try {
+      stamp = Math.trunc(fsv.statSync(path).mtimeMs)
+    } catch {}
+    return normalize(parsed, stamp)
+  }
+
+  function read() {
+    return readFrom(snapshotPath)
+  }
+
   function write(plan) {
     if (plan === null || typeof plan !== 'object' || Array.isArray(plan)) return null
-    const record = { ...plan, version: 2 }
+    const record = { ...plan, version: CURRENT_VERSION }
     return atomicWrite(snapshotPath, record) ? record : null
   }
 
-  function appendJournal(planId, key) {
+  /** The crash plan survives this process: it is written before the heartbeat overwrites its file. */
+  function readPending() {
+    return readFrom(pendingPath)
+  }
+
+  function writePending(plan) {
+    if (plan === null || typeof plan !== 'object' || Array.isArray(plan)) return null
+    const record = { ...plan, version: CURRENT_VERSION }
+    return atomicWrite(pendingPath, record) ? record : null
+  }
+
+  function clearPending() {
+    try {
+      fsv.rmSync(pendingPath, { force: true })
+      syncDir(dir)
+      return true
+    } catch (error) {
+      log(`cannot clear pending plan: ${error?.message ?? error}`)
+      return false
+    }
+  }
+
+  /**
+   * Journals carry the boot that wrote each row. A row from an earlier process is evidence for the
+   * summary, never permission to skip work: the only things a new process can trust are the live
+   * Harness and the plan itself.
+   */
+  function appendJournal(planId, key, status, bootId) {
     let line = null
     try {
-      line = JSON.stringify({ k: key })
+      line = JSON.stringify({ k: key, s: status ?? 'ok', b: bootId ?? null, at: now() })
     } catch {
       return false
     }
@@ -127,23 +218,23 @@ export function createStore(dir, options = {}) {
   }
 
   function readJournal(planId) {
-    const done = new Set()
+    const rows = new Map()
     let raw = ''
     try {
       raw = fsv.readFileSync(journalPath(planId), 'utf8')
     } catch {
-      return done
+      return rows
     }
     for (const line of raw.split('\n')) {
       if (line === '') continue
       try {
         const row = JSON.parse(line)
-        if (typeof row?.k === 'string') done.add(row.k)
+        if (typeof row?.k === 'string') rows.set(row.k, { status: typeof row.s === 'string' ? row.s : 'ok', boot: typeof row.b === 'string' ? row.b : null })
       } catch {
         // A torn last line is a write that never finished, not a key that was restored.
       }
     }
-    return done
+    return rows
   }
 
   function clearJournal(planId) {
@@ -152,47 +243,78 @@ export function createStore(dir, options = {}) {
     } catch {}
   }
 
+  function writeResult(record) {
+    return atomicWrite(lastRestorePath, record)
+  }
+
   /**
    * The plan is spent: archive it, publish the record the UI reads, and only then remove it. A plan
-   * that could not be archived stays on disk, so the same work is never claimed twice.
+   * that could not be archived stays on disk, so the same work is never claimed twice. A snapshot
+   * that could not be removed is reported as a failure even though the archive landed: the next
+   * reader would otherwise see a plan that is already restored and try to restore it again.
    */
   function consume(plan, summary) {
     const source = plan !== null && typeof plan === 'object' && !Array.isArray(plan) ? plan : {}
     const archivePath = join(restoresDir, `${sanitize(source.planId)}.json`)
     const record = { ...source, status: 'restored', restoredAt: new Date(now()).toISOString(), summary }
     const archived = atomicWrite(archivePath, record)
-    const published = archived && atomicWrite(lastRestorePath, record)
+    const published = archived && writeResult(record)
     if (published === false) {
       log('cannot archive the restored plan: the snapshot stays')
-      return { ok: false, archivePath: null }
+      return { ok: false, archivePath: null, published: false }
     }
     const current = read()
     // Another press may have written a newer plan while this one restored; that one is not ours.
-    if (current !== null && current.planId === source.planId) {
+    if (current === null || current.planId === source.planId) {
       try {
         fsv.rmSync(snapshotPath, { force: true })
-      } catch {}
+        syncDir(dir)
+      } catch (error) {
+        log(`cannot clear the restored plan: ${error?.message ?? error}`)
+        return { ok: false, archivePath, published: true }
+      }
     }
     clearJournal(source.planId)
-    return { ok: true, archivePath }
+    return { ok: true, archivePath, published: true }
   }
 
   function lastRestore() {
+    const parsed = parse(lastRestorePath)
+    return parsed
+  }
+
+  function hasSnapshot() {
     try {
-      const parsed = JSON.parse(fsv.readFileSync(lastRestorePath, 'utf8'))
-      return parsed !== null && typeof parsed === 'object' ? parsed : null
+      return fsv.existsSync(snapshotPath) === true
     } catch {
-      return null
+      return false
     }
   }
 
-  function hasSnapshot() {
+  function hasPending() {
     try {
-      return fsv.existsSync(snapshotPath) === true
+      return fsv.existsSync(pendingPath) === true
     } catch {
       return false
     }
   }
 
-  return { dir, snapshotPath, read, write, appendJournal, readJournal, clearJournal, consume, lastRestore, hasSnapshot }
+  return {
+    dir,
+    snapshotPath,
+    pendingPath,
+    read,
+    write,
+    readPending,
+    writePending,
+    clearPending,
+    appendJournal,
+    readJournal,
+    clearJournal,
+    writeResult,
+    consume,
+    lastRestore,
+    hasSnapshot,
+    hasPending,
+  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-pause-resume",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "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",