dsh-pause-resume 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+## 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

@@ -40,15 +40,22 @@ 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.
+
+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:
 `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 +81,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 +99,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

@@ -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 ''
     }
@@ -172,24 +175,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

@@ -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.2.0'
+export const VERSION = '0.4.0'
 
 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 = [
@@ -147,7 +153,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),
     ],
@@ -170,6 +176,7 @@ function serve(ctx, engine, heartbeat, options) {
     }
   }
   return () => {
+    disposed = true
     for (const dispose of disposers) {
       try {
         dispose()
@@ -212,10 +219,13 @@ 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,
   })
@@ -224,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 {}
@@ -263,20 +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 {
-      // 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()
-      if (disposed) return
-      await engine.hydrate()
+      // 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()
+      const hydrated = await engine.hydrate({ residue })
       if (disposed) return
-      const dispose = serve(ctx, engine, heartbeat, { allowRemote })
-      if (disposed) dispose()
-      else disposeRoutes = dispose
+      // 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()
       log(`ready (${engine.phase})`)
     } catch (error) {
       log(`cannot start: ${error?.message ?? error}`)
+    } finally {
+      releaseReady()
     }
   })()