dsh-pause-resume 0.2.0 → 0.4.0

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 {
@@ -66,10 +68,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 +122,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,7 +143,15 @@ 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() {
+    if (writable === false) return false
     return dirty() ? persist(pending) : true
   }
 
@@ -207,16 +228,25 @@ 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)
   }
 
   return {
     note,
+    peek,
     start,
     stop,
+    hold,
     release,
     flush,
     get residue() {

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()
@@ -224,12 +232,17 @@ 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 }],
-      mode: 'followup',
+      // `queue` is the shipped public mode: deliver after the current turn, start one when idle.
+      mode: 'queue',
     }
   }
 
@@ -237,7 +250,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
     }
@@ -262,29 +279,70 @@ 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.
-    const lastTurn = lastTurnOf(agent)
-    if (agent.status === 'running' || (Number.isSafeInteger(session.lastTurn) && lastTurn !== null && lastTurn > session.lastTurn)) {
-      return { status: 'skipped', detail: 'already continued', continued: false }
+    // 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') 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 {
-      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,29 +356,47 @@ 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' }
+    }
+    // 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') {
+      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 === 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) }
     }
-    return { status: 'restored', detail: 'armed' }
+    const after = goalView(services, agent)
+    return { status: 'restored', detail: 'armed', revision: after?.revision ?? null }
   }
 
   /**
@@ -333,10 +409,10 @@ 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: 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 +420,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,124 @@ 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
+    // `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
+  }
+
+  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 +236,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 +261,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,
+  }
 }