dsh-pause-resume 0.1.0 → 0.2.0

package/README.md

@@ -1,34 +1,62 @@
 # dsh-pause-resume
 
-One button in the DeepSeek Harness session header. It stops everything that is running, and after a
-restart the same button puts that work back.
+One button in the DeepSeek Harness session header. It stops what is running, writes a small plan to
+disk, and after a restart the same button puts that work back.
 
 * ⏸ — work is running. Press to stop it.
-* ▶ — work is stopped, or a previous run ended mid-turn. Press to restore it.
+* ▶ — work is stopped, or a previous process died mid-turn. Press to restore it.
 * ⏸ dimmed — nothing to stop and nothing to restore.
 
 The glyph is the only status. There is no counter, no panel and no toast, because a status badge next
-to the button would be a second source of truth for the same fact.
+to the button would be a second source of truth for the same fact. A red dot is added only when the
+last press left something for a person to look at.
 
 ## What it restores
 
 | Work | Pause | Restore |
 | --- | --- | --- |
-| A session with an unfinished turn | turn cancelled, session recorded | session resumed |
-| An armed goal | paused, with its revision | resumed with the same revision; the goal driver continues on its own |
+| A session with an unfinished turn | turn cancelled, session recorded | session mounted, then one visible continuation message |
+| A goal that was armed | paused with the revision it had | `goals.resume` with that exact revision; the goal driver continues on its own |
+| A session that only carried that goal | recorded, nothing stopped | mounted; the resumed goal takes over |
 | A running background job | killed and recorded | recorded only: a job is a live process, not replayable |
-| A terminal | untouched | untouched — that process is not the plugin's to end |
-| An open tab / finished session | untouched | untouched |
+| A session that ended normally | untouched | untouched, and never recorded in the first place |
+| A terminal / finished session | untouched | untouched |
+| A schedule | untouched | untouched |
 
-A session that ended normally is never restored: the decision is made from the turn the session's log
-ends with, not from how the session list happens to colour it.
+Schedules are not paused: the schedule service has no disable operation, only delete, and deleting a
+person's schedule to pause it is not a trade this plugin makes. A schedule that fires while paused
+starts a turn; the button then shows ⏸ again, truthfully.
+
+## How resume works
+
+A restore is not a claim that work continued. It is three honest steps per item:
+
+1. **Mount.** A stopped session is mounted through the Harness resume path, which preserves its agent
+   preset. If it is already mounted, that step is skipped.
+2. **Continue, only where the press actually cancelled a turn.** The continuation is one ordinary
+   user message sent through `sessionController.prompt`, with a request id derived from the plan and
+   the session. The id makes a repeated restore idempotent, and the message is visible in the
+   transcript, so the person can see exactly what was resumed.
+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.
 
 ## 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 one's heartbeat and offers ▶ with no press needed. The same
-process reloading the plugin (hot reload) sees its own id and knows there is nothing to restore.
+it. A new process finds the previous process's record 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
+type a continuation message on their behalf. Sessions that ended normally never enter the file.
+
+The same process reloading the plugin (hot reload) sees its own id and knows there is nothing to
+restore. A `pausing` plan found on disk means the press itself was interrupted: those sessions are
+mounted but never continued, and the button carries a dot until a person presses restore.
 
 ## Installing
 
@@ -37,24 +65,25 @@ plugin_manager install_bundle dsh-pause-resume
 ```
 
 or install the bundle from the Harness plugin manager with the package name. The plugin needs no
-configuration and holds no credentials.
+configuration and holds no credentials. `allowRemote` exists for a Harness reached from another
+machine; local-only is the default.
 
 ## Guarantees and limits
 
 * **Exclusive.** The phase lives on the Host and is written before any work starts, so two windows,
   a double press and a tool call cannot overlap. The second caller is told `busy`.
-* **Idempotent.** A restore journals every item it finished. A crash in the middle of a restore
-  continues with the remainder instead of restoring the same session twice.
-* **Honest.** Disk that cannot be written 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.
-* **Schedules are not paused.** The schedule service has no disable operation, only delete, and
-  deleting a person's schedule to pause it is not a trade this plugin makes. A schedule that fires
-  while paused starts a turn; the button then shows ⏸ again, truthfully.
-* **No third-party plugin state.** A plugin's in-process state belongs to that plugin's mount. There
-  is a seam for a plugin that owns durable state, but nothing is restored on someone else's behalf.
-* **No synthetic prompts.** Nothing is typed into a person's session on their behalf. A goal
-  continues because the Harness has a mechanism for that; a plain session is put back at the turn it
-  was interrupted in.
+* **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.
+* **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
+  "turns cancelled, goals paused, jobs killed" — not "the process is frozen". A goal continues because
+  the Harness has a mechanism for that; a plain session continues through one visible user message.
+* **No third-party plugin state.** A plugin's in-process state belongs to that plugin's mount.
+* **Local by default.** The routes require a same-origin request and a plugin header. Remote use must
+  be opted into and still cannot skip the header.
 
 ## Files
 
@@ -62,28 +91,31 @@ All state lives under `$DSH_HOME/pause-resume/`:
 
 | File | Purpose |
 | --- | --- |
-| `snapshot.json` | the work a press stopped |
+| `snapshot.json` | the work a press stopped, `pausing` or `paused` |
+| `journal/<planId>.jsonl` | restore items already finished |
+| `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 |
-| `restore.jsonl` | restore steps already done |
-| `last-restore.json` | record of the last restore |
 
-Every write is temp file + `fsync` + `rename`. State is never inside the package.
+Every write is a unique temp file, `fsync`, `rename`, then a directory `fsync`. State is never inside
+the package.
 
 ## Development
 
 ```bash
-node --test --test-timeout=15000 'test/*.test.mjs'
+npm test
+npm run audit
 ```
 
 `lib/engine.js` performs no I/O, `lib/snapshot.js` persists, `lib/probe.js` holds every Harness service
-contract (listing shape, goal addressing, per-owner jobs), and `index.js` only wires them to the web
-routes. All four are testable without a Harness: `test/apply.test.mjs` mounts the plugin against a fake
-registry and fails if a service call is stale, which is how the `{ items }` listing bug was caught.
+contract (agent identity, goal revision, per-owner jobs, continuation prompts), and `index.js` only
+wires them to the web routes. All of them are testable without a Harness: `test/apply.test.mjs` mounts
+the plugin against a fake registry.
 
 MIT.
 
 ---
 
 一行说明：会话头一个按钮，⏸ 停掉正在跑的回合、目标与后台任务；重启后同一个按钮变 ▶，把上次的工作
-接回来。崩溃也能识别：靠心跳文件，不靠人按过按钮。日程不会被动（该服务只有删除，没有停用），
-后台命令只记录不重跑。
+接回来。正常结束的会话不记录、不恢复；崩溃靠心跳文件识别，但只挂载不代发消息；日程不会被动
+（该服务只有删除，没有停用），后台命令只记录不重跑。

package/client.js

@@ -1,13 +1,29 @@
 window.__ModuleLoader__.load({
-  id: 'dsh-pause-resume',
+  id: 'dsh-pause-resume', // ui-copy-ignore
   factory(require) {
     const React = require('react')
     const h = React.createElement
 
     const zh = /^zh/i.test(navigator.language || '')
     const COPY = zh
-      ? { pause: '暂停', resume: '继续', busy: '正在处理' }
-      : { pause: 'Pause', resume: 'Resume', busy: 'Working' }
+      ? {
+          pause: '暂停', // ui-copy-ignore
+          resume: '继续', // ui-copy-ignore
+          busy: '正在处理', // ui-copy-ignore
+          error: '上次操作没有完成', // ui-copy-ignore
+          partial: '部分内容未能恢复，可以再按一次', // ui-copy-ignore
+          stopped: '上次暂停的内容还没有恢复', // ui-copy-ignore
+          attention: '有内容需要你处理',
+        }
+      : {
+          pause: 'Pause', // ui-copy-ignore
+          resume: 'Resume', // ui-copy-ignore
+          busy: 'Working', // ui-copy-ignore
+          error: 'The last action did not finish',
+          partial: 'Some items were not restored; press again to retry',
+          stopped: 'Work is still stopped',
+          attention: 'Some items need a look',
+        }
 
     const HOST_BASE = '/dsh-pause-resume' // ui-copy-ignore
     const POLL_MS = 2000 // ui-copy-ignore
@@ -18,7 +34,17 @@ window.__ModuleLoader__.load({
      * Host owns the phase and this asks for it. Until an answer arrives the button renders the // ui-copy-ignore
      * settled state (`none`), never a spinner, so a slow Host cannot look like a running press. // ui-copy-ignore
      */
-    const EMPTY = { phase: 'idle', action: 'none', source: null, complete: null, counts: { sessions: 0, goals: 0, schedules: 0, jobs: 0 }, live: { sessions: 0, goals: 0, jobs: 0 }, error: null }
+    const EMPTY = {
+      phase: 'idle', // ui-copy-ignore
+      action: 'none', // ui-copy-ignore
+      source: null, // ui-copy-ignore
+      complete: null, // ui-copy-ignore
+      outstanding: 0,
+      counts: { sessions: 0, goals: 0, jobs: 0 },
+      live: { sessions: 0, goals: 0, jobs: 0 },
+      attention: 0,
+      error: null, // ui-copy-ignore
+    }
 
     function withTimeout(promise, ms = REQUEST_MS) {
       let id = null
@@ -28,9 +54,9 @@ window.__ModuleLoader__.load({
       return Promise.race([promise, timer]).finally(() => clearTimeout(id))
     }
 
-    async function readState() {
+    async function readState(signal) {
       try {
-        const response = await withTimeout(fetch(`${HOST_BASE}/state`, { cache: 'no-store', credentials: 'same-origin' }))
+        const response = await withTimeout(fetch(`${HOST_BASE}/state`, { cache: 'no-store', credentials: 'same-origin', signal })) // ui-copy-ignore
         if (!response.ok) return null
         const data = await withTimeout(response.json())
         return data !== null && typeof data === 'object' ? data : null
@@ -39,13 +65,14 @@ window.__ModuleLoader__.load({
       }
     }
 
-    async function press(action) {
+    async function press(action, signal) {
       try {
         const response = await withTimeout(fetch(`${HOST_BASE}/${action}`, {
           method: 'POST', // ui-copy-ignore
           credentials: 'same-origin',
           headers: { 'content-type': 'application/json', 'x-dsh-pause-resume': '1' }, // ui-copy-ignore
           body: '{}', // ui-copy-ignore
+          signal,
         }))
         if (!response.ok) return null
         const data = await withTimeout(response.json())
@@ -110,49 +137,93 @@ window.__ModuleLoader__.load({
     }, h('path', { d: 'M5.2 3.4a.7.7 0 0 0-1.05.6v8a.7.7 0 0 0 1.05.6l6.9-4a.7.7 0 0 0 0-1.2l-6.9-4z' }))
     const SPIN_GLYPH = icon(['M8 2.5a5.5 5.5 0 1 1-4.3 2.06'], SPIN_STYLE)
 
+    /** The one sentence behind the dot, in the tooltip only: the button itself stays a glyph. */
+    function hintOf(state) {
+      if (state.error === 'restore-partial') return COPY.partial
+      if (state.error !== null && state.error !== undefined) return COPY.error
+      if ((state.attention ?? 0) > 0) return COPY.attention
+      if ((state.outstanding ?? 0) > 0) return COPY.stopped
+      return ''
+    }
+
     function Button() {
       const [state, setState] = React.useState(EMPTY)
       const [hover, setHover] = React.useState(false)
+      const [pressing, setPressing] = React.useState(false)
       const mounted = React.useRef(true)
+      /** Each answer carries a number: a slow reply may never overwrite a newer one. */
+      const seq = React.useRef(0)
+      const inflight = React.useRef(null)
+
+      const apply = React.useCallback((next) => {
+        if (!mounted.current || next === null) return
+        seq.current += 1
+        setState({ ...EMPTY, ...next })
+      }, [])
+
+      const pull = React.useCallback(async (signal) => {
+        const mine = seq.current
+        const next = await readState(signal)
+        if (!mounted.current || seq.current !== mine) return
+        if (next !== null) apply(next)
+      }, [apply])
 
       React.useEffect(() => {
         ensureStyle()
         mounted.current = true
         let timer = null
-        const pull = async () => {
-          const next = await readState()
-          if (!mounted.current) return
-          if (next !== null) setState({ ...EMPTY, ...next })
+        let current = null
+        const beat = () => {
+          if (document.visibilityState !== 'visible' || inflight.current !== null) return
+          try {
+            current?.abort()
+          } catch {}
+          current = typeof AbortController === 'function' ? new AbortController() : null
+          void pull(current?.signal)
         }
-        pull()
-        timer = setInterval(() => {
-          if (document.visibilityState === 'visible') pull()
-        }, POLL_MS)
+        beat()
+        timer = setInterval(beat, POLL_MS)
         const onVisible = () => {
-          if (document.visibilityState === 'visible') pull()
+          if (document.visibilityState === 'visible') beat()
         }
         document.addEventListener('visibilitychange', onVisible)
         return () => {
           mounted.current = false
           if (timer !== null) clearInterval(timer)
+          try {
+            current?.abort()
+          } catch {}
           document.removeEventListener('visibilitychange', onVisible)
         }
-      }, [])
+      }, [pull])
 
-      const busy = state.action === 'busy'
+      const busy = pressing || state.action === 'busy'
       const action = state.action === 'pause' || state.action === 'resume' ? state.action : null
       const disabled = action === null && !busy
 
       const onClick = async () => {
-        if (busy || action === null) return
-        // The phase is set from the Host's answer, never optimistically: the spinner appears when // ui-copy-ignore
-        // the Host says it started, so two windows can never show different phases. // ui-copy-ignore
-        setState((current) => ({ ...current, action: 'busy' }))
-        const answer = await press(action)
-        const next = await readState()
-        if (!mounted.current) return
-        if (next !== null) setState({ ...EMPTY, ...next })
-        else if (answer === null) setState((current) => ({ ...current, action }))
+        if (busy || action === null || inflight.current !== null) return
+        // One press at a time, in this tab and across tabs: the Host also refuses an overlapping // ui-copy-ignore
+        // press, so a second window's button settles on the same answer instead of starting work.
+        const controller = typeof AbortController === 'function' ? new AbortController() : null
+        inflight.current = controller
+        setPressing(true)
+        try {
+          const answer = await press(action, controller?.signal)
+          const next = answer ?? (await readState())
+          if (mounted.current) {
+            if (next !== null) {
+              seq.current += 1
+              setState({ ...EMPTY, ...next })
+            } else {
+              // The press may still have landed: ask again rather than guessing the phase.
+              void pull(controller?.signal)
+            }
+          }
+        } finally {
+          inflight.current = null
+          if (mounted.current) setPressing(false)
+        }
       }
 
       const style = busy || disabled
@@ -163,6 +234,7 @@ window.__ModuleLoader__.load({
 
       const glyph = busy ? SPIN_GLYPH : action === 'resume' ? PLAY_GLYPH : PAUSE_GLYPH
       const label = busy ? COPY.busy : action === 'resume' ? COPY.resume : COPY.pause
+      const hint = hintOf(state)
 
       return h('button', {
         type: 'button', // ui-copy-ignore
@@ -171,9 +243,10 @@ window.__ModuleLoader__.load({
         disabled,
         'aria-label': label,
         'aria-busy': busy,
+        title: hint === '' ? label : `${label} · ${hint}`,
         onMouseEnter: () => setHover(true),
         onMouseLeave: () => setHover(false),
-      }, glyph, state.error === null || state.error === undefined ? null : h('span', { style: DOT_STYLE, 'aria-hidden': true }))
+      }, glyph, hint === '' ? null : h('span', { style: DOT_STYLE, 'aria-hidden': true }))
     }
 
     return {

package/index.js

@@ -6,11 +6,12 @@ import { createHeartbeat } from './lib/heartbeat.js'
 import { createProbe, listRunning } from './lib/probe.js'
 
 export const name = 'dsh-pause-resume'
-export const VERSION = '0.1.0'
+export const VERSION = '0.2.0'
 
 const BASE_PATH = '/dsh-pause-resume'
 const BUTTON_HEADER = 'x-dsh-pause-resume'
 const BOOT_KEY = Symbol.for('dsh-pause-resume.boot')
+const LIVENESS_MS = 400
 
 /** A page this machine may have opened. A public name that resolves here is the rebinding case. */
 const LOCAL_ADDRESS =
@@ -38,7 +39,6 @@ function bootId() {
   return created
 }
 
-
 function service(ctx, key) {
   try {
     return ctx.get(key)
@@ -49,8 +49,8 @@ function service(ctx, key) {
 
 function sendJson(res, status, value) {
   try {
-    const body = JSON.stringify(value ?? { status: 'error' })
     if (res?.headersSent === true) return res.end()
+    const body = JSON.stringify(value ?? { status: 'error' })
     res.writeHead(status, {
       'content-type': 'application/json; charset=utf-8',
       'cache-control': 'no-store',
@@ -66,13 +66,18 @@ function sendJson(res, status, value) {
   }
 }
 
-/** Whether one request may act for the button: a header a cross-site form cannot set, same origin. */
-function buttonAllowed(req) {
+/**
+ * Whether one request may act for the button: a header a cross-site form cannot set, and the same
+ * origin that served this page. `allowRemote` widens the address check, never the header or origin
+ * check, so a hostile page cannot press the button even on a trusted network.
+ */
+function buttonAllowed(req, allowRemote) {
   try {
     const header = req?.headers?.[BUTTON_HEADER]
     if (typeof header !== 'string' || header === '') return false
     const site = typeof req?.headers?.host === 'string' ? req.headers.host.trim().toLowerCase() : '' // ui-copy-ignore
-    if (site !== '' && LOCAL_ADDRESS.test(site) === false) return false
+    if (site === '') return false
+    if (allowRemote !== true && LOCAL_ADDRESS.test(site) === false) return false
     const origin = typeof req?.headers?.origin === 'string' ? req.headers.origin.trim().toLowerCase() : ''
     if (origin === 'null') return false
     if (origin !== '') {
@@ -112,50 +117,53 @@ function guard(handler) {
   }
 }
 
-function serve(ctx, engine, heartbeat) {
+function serve(ctx, engine, heartbeat, options) {
   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
+  const route = (handler, read) => guard(async (req, res) => {
+    const method = String(req?.method ?? 'GET').toUpperCase()
+    if (read === true ? method !== 'GET' && method !== 'HEAD' : method !== 'POST') {
+      return sendJson(res, 405, { status: 'method' })
+    }
+    // A read still refuses another origin, but it does not need the button header.
+    if (read === true ? sameOrigin(req, allowRemote) === false : buttonAllowed(req, allowRemote) === false) {
+      return sendJson(res, 403, { status: 'forbidden' })
+    }
+    return handler(req, res)
+  })
   const handlers = [
     [
       `${BASE_PATH}/state`,
-      async (req, res) => {
-        const method = String(req?.method ?? 'GET').toUpperCase()
-        if (method !== 'GET' && method !== 'HEAD') return sendJson(res, 405, { status: 'method' })
-        sendJson(res, 200, await engine.describe())
-      },
+      route(async (req, res) => {
+        sendJson(res, 200, engine.describe())
+      }, true),
     ],
     [
       `${BASE_PATH}/pause`,
-      async (req, res) => {
-        const method = String(req?.method ?? 'GET').toUpperCase()
-        if (method !== 'POST') return sendJson(res, 405, { status: 'method' })
-        if (buttonAllowed(req) === false) return sendJson(res, 403, { status: 'forbidden' })
+      route(async (req, res) => {
         const outcome = await engine.pause()
         log(`pause: ${outcome.status}${outcome.status === 'busy' ? ` (${outcome.phase})` : ''}`)
         if (outcome.status === 'paused') heartbeat.release()
-        sendJson(res, 200, { ...(await engine.describe()), outcome })
-      },
+        sendJson(res, 200, { ...engine.describe(), outcome })
+      }, false),
     ],
     [
       `${BASE_PATH}/resume`,
-      async (req, res) => {
-        const method = String(req?.method ?? 'GET').toUpperCase()
-        if (method !== 'POST') return sendJson(res, 405, { status: 'method' })
-        if (buttonAllowed(req) === false) return sendJson(res, 403, { status: 'forbidden' })
+      route(async (req, res) => {
         const outcome = await engine.resume()
         log(`resume: ${outcome.status}`)
-        if (outcome.status === 'resumed') heartbeat.release()
-        sendJson(res, 200, { ...(await engine.describe()), outcome })
-      },
+        sendJson(res, 200, { ...engine.describe(), outcome })
+      }, false),
     ],
   ]
   const disposers = []
   for (const [path, handler] of handlers) {
     try {
-      const dispose = server.register({ kind: 'exact', path, handler: guard(handler) })
+      const dispose = server.register({ kind: 'exact', path, handler })
       if (typeof dispose === 'function') disposers.push(dispose)
     } catch (error) {
       log(`cannot answer ${path}: ${error?.message ?? error}`)
@@ -170,39 +178,102 @@ function serve(ctx, engine, heartbeat) {
   }
 }
 
+/** Same-origin read: a page on another host may not learn what is running here. */ // ui-copy-ignore
+function sameOrigin(req, allowRemote) {
+  try {
+    const site = typeof req?.headers?.host === 'string' ? req.headers.host.trim().toLowerCase() : '' // ui-copy-ignore
+    if (site === '') return false
+    if (allowRemote !== true && LOCAL_ADDRESS.test(site) === false) return false
+    const origin = typeof req?.headers?.origin === 'string' ? req.headers.origin.trim().toLowerCase() : ''
+    if (origin === 'null') return false
+    if (origin === '') return true
+    try {
+      return new URL(origin).host.toLowerCase() === site // ui-copy-ignore
+    } catch {
+      return false
+    }
+  } catch {
+    return false
+  }
+}
+
 export function apply(ctx, config = {}) {
   const dir = dataDir()
-  const store = createStore(dir)
+  const allowRemote = config?.allowRemote === true
+  const store = createStore(dir, { log })
   const heartbeat = createHeartbeat({
     dir,
     bootId: bootId(),
+    intervalMs: Number.isFinite(config?.intervalMs) ? config.intervalMs : 5000,
     listRunning: () => listRunning(ctx),
     log,
   })
+  const probe = createProbe(ctx, {
+    graceMs: Number.isFinite(config?.graceMs) ? config.graceMs : 2000,
+    continueText: typeof config?.continueText === 'string' ? config.continueText : undefined,
+  })
   const engine = createEngine({
     store,
-    probe: createProbe(ctx, heartbeat),
+    probe,
+    heartbeat,
     graceMs: Number.isFinite(config?.graceMs) ? config.graceMs : 2000,
-    gapMs: Number.isFinite(config?.gapMs) ? config.gapMs : 150,
     log,
   })
 
+  let disposed = false
   let disposeRoutes = () => {}
   const cleanup = () => {
+    disposed = true
     try {
       disposeRoutes()
     } catch {}
+    // A reload is not a crash: keep the heartbeat's last write as evidence, but let go of timers.
     heartbeat.stop()
   }
 
   if (typeof ctx.effect === 'function') ctx.effect(() => cleanup)
   else if (typeof ctx.on === 'function') ctx.on('dispose', cleanup)
 
+  // Turn edges are what a crash loses first, so the heartbeat follows them instead of waiting for its
+  // own interval. The interval stays as the fallback for a registry that changes shape silently.
+  let liveness = null
+  const noteRunning = () => {
+    if (disposed) return
+    try {
+      heartbeat.note(listRunning(ctx))
+    } catch (error) {
+      log(`cannot note running work: ${error?.message ?? error}`)
+    }
+  }
+  const watchStatus = () => {
+    if (liveness !== null) clearTimeout(liveness)
+    liveness = setTimeout(() => {
+      liveness = null
+      noteRunning()
+    }, LIVENESS_MS)
+    if (typeof liveness?.unref === 'function') liveness.unref()
+  }
+  try {
+    if (typeof ctx.on === 'function') {
+      ctx.on('agent/status', watchStatus)
+      ctx.on('agent/dispose', watchStatus)
+      ctx.on('agent/register', watchStatus)
+    }
+  } catch (error) {
+    log(`cannot follow agent events: ${error?.message ?? error}`)
+  }
+
   void (async () => {
     try {
-      await engine.hydrate()
+      // 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()
-      disposeRoutes = serve(ctx, engine, heartbeat)
+      if (disposed) return
+      await engine.hydrate()
+      if (disposed) return
+      const dispose = serve(ctx, engine, heartbeat, { allowRemote })
+      if (disposed) dispose()
+      else disposeRoutes = dispose
       log(`ready (${engine.phase})`)
     } catch (error) {
       log(`cannot start: ${error?.message ?? error}`)