@maci0/dsh-restore 0.8.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marcel W. Wysocki
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,102 @@
+# dsh-restore
+
+A browser-style restore bar for DeepSeek Harness: after a reboot or crash, one
+click resumes the goals and continues every session that was mid-flight. After
+a restart the harness closes each cut-off turn and disarms every goal, then
+waits; nothing tells you which of dozens of sessions were working.
+
+![restore bar](docs/restore-bar.png)
+
+## What you get
+
+- A bar at the top of the app, shown once after a restart that cut sessions
+  off: "DeepSeek Harness stopped while N sessions were still working."
+- **Show** lists them by title, marked goal or turn; click one to open it.
+- **Restore** resumes every goal that is still `active` and sends `continue`
+  to every other session. **Dismiss** forgets the set.
+
+## Install
+
+> **Install it as a bundle.** `dsh plugin add …` mounts the row from the
+> package's own patch layer, which is what the settings editor can write to. A
+> row added with `--patch` is an overlay: it disappears at the next start.
+
+```sh
+dsh plugin --profile web add @maci0/dsh-restore@0.8.2
+```
+
+This installs the public npm package; no GitHub token or `~/.secrets` setup is needed.
+The version is pinned. To upgrade, run the same command with a newer version,
+then restart `dsh web` (bundle layers compose at boot).
+
+Needs the Web/desktop bundle (`webServer`, `sessionController`); headless
+profiles do not mount them.
+
+## How it works
+
+Two sources feed the pending set. State lives in
+`$DSH_HOME/storages/dsh-restore/` (default `~/.dsh/storages/`): a shared
+`pending.json`, and one `live-<pid>.json` per running harness process. Shared
+edits hold the native SQLite writer lock in `pending.lock.sqlite`, which is
+released automatically if a process dies. A dead live record is retired only
+after its recovery entries have been saved; failed saves leave the bar intact.
+
+- **The live record.** While dsh runs, the plugin lists every session with a
+  turn in progress or a goal armed, rewritten atomically on each `turn/start`,
+  `turn/end`, and goal activation change. A turn aborted as `disposed` (a
+  shutdown) stays listed, so a clean reboot counts the same as a crash; a turn
+  you stopped yourself does not. Each process writes only its own record, so
+  two harness processes on one home never overwrite each other. At the next
+  start, records whose process is gone (another boot id, a pid no longer
+  running, or a pid whose process started at another time) move to pending; a
+  running process keeps its own.
+- **The boot scan.** For hard crashes, including ones from before the plugin
+  was installed, it finds logs whose last turn no process closed: an open
+  `turn/start`, or the `interrupted` closer the harness writes when such a
+  session is reopened. It stats the JSONL store (the `root` of the
+  `session-persistence-jsonl` row, so a moved store is found) and opens only logs
+  changed in the last 3 days, and remembers how far it has offered, so a
+  dismissed crash stays dismissed. Titles and goal state come from the same
+  read.
+
+**Restore** opens each pending session through the session controller and:
+
+- resumes its goal when the goal is still `active` (the goal round driver then
+  queues the round, exactly like `/goal resume`);
+- otherwise sends `continue` as a user message;
+- skips a session that is already running.
+
+A session whose writer lock is held by another process, or that hit a gateway
+error, stays in the bar for another Restore. Deleted sessions and subagent
+children drop out; a parent's resume reaches its children. Paused, blocked, and
+completed goals are never touched. Two Restore clicks at once (two tabs) run
+one restore.
+
+The browser half talks to the host over `GET`/`POST /restore`, behind the
+web server's connection fence; a POST must carry a JSON body. The bar
+re-reads the set when its tab comes back into view, so a Restore or Dismiss
+in another tab is reflected.
+
+## Limits
+
+- A profile that persists sessions without the JSONL store gets no boot scan,
+  only the live record, and the plugin logs that.
+- Crashes older than 3 days are treated as history and not offered.
+- Off Linux (no procfs start times or boot id), a pid reused by another
+  process reads as a running owner, so that record is offered once the pid's
+  new holder exits.
+
+## Development
+
+```sh
+bun test   # unit suite, the restore bar, and a real Cordis composition mount
+```
+
+For local development, install the checkout into a profile with
+`dsh plugin --profile <name> add <path-to-checkout>`.
+
+dsh loads plugins on Node `^22.19.0 || >=24.0.0`; development and tests run on bun.
+
+## Licence
+
+MIT. See [LICENSE](LICENSE).

package/cordis.patch.yml

@@ -0,0 +1,6 @@
+# Bundle layer: applied when a profile lists this bundle in dsh.profile.bundles
+# (dsh plugin add does that from dsh.bundle). Do not also paste this row into
+# the profile's cordis.patch.yml: insert does not dedupe ids.
+- insert:
+    - id: restore
+      name: '@maci0/dsh-restore'

package/icon.svg

@@ -0,0 +1,4 @@
+<svg width="36" height="36" viewBox="0 0 36 36" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <path d="M13 10.5v15l11-7.5z" stroke="#145AF3" stroke-width="2.4" stroke-linejoin="round"/>
+  <path d="M9 9v18" stroke="#145AF3" stroke-width="2.4" stroke-linecap="round"/>
+</svg>

package/index.js

@@ -0,0 +1,503 @@
+/**
+ * dsh-restore: offer to resume every session that was mid-flight when the
+ * harness last went down (reboot, crash, kill), the way a browser offers to
+ * restore its tabs.
+ *
+ * While running, each harness process keeps its own live record listing every
+ * session with a turn in progress or a goal armed, rewritten on every change,
+ * so whatever is on disk when the process dies is its in-flight set. At the
+ * next start, records of processes that are gone move to the shared `pending`
+ * set. A boot scan of the stored logs adds every session whose last turn no
+ * process closed (a hard crash, including one from before this plugin was
+ * installed), and the browser half shows a restore bar.
+ * Restore resumes a session's goal when it is still `active` (the harness
+ * disarms every goal on restart) and sends `continue` to any other session.
+ *
+ * Route `/restore`:
+ *   GET                             → { pending: [{ id, cwd, since, turn, goal }] }
+ *   POST { "action": "restore" }    → { results: [{ id, outcome }], pending }
+ *   POST { "action": "dismiss" }    → { results: [], pending: [] }
+ * `pending` after a POST is what the host could not settle (a writer lock
+ * held by another process, a gateway fault), kept for the next restore.
+ */
+import { readFileSync, writeFileSync, renameSync, mkdirSync, readdirSync, rmSync, statSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+import { DatabaseSync } from 'node:sqlite'
+import { createUserMessage } from '@deepseek-ai/dsh-llm/message'
+
+export const name = 'restore'
+export const inject = ['webServer', 'sessionController', 'goals', 'sessions', 'sessionPersistence']
+
+/** The route the browser half reads and posts to. */
+export const ROUTE = '/restore'
+const CONTINUE_MESSAGE = 'continue'
+const STATE_VERSION = 2
+/** Cut-off turns older than this are history, not a crash to recover from. */
+const MAX_CRASH_AGE_MS = 3 * 24 * 60 * 60 * 1000
+/** Largest POST body accepted; the real ones are a few dozen bytes. */
+const MAX_BODY_BYTES = 1024
+
+/** The harness home: `$DSH_HOME`, else `~/.dsh`, resolved like the harness resolves it. */
+function dshHome(env = process.env) {
+  return resolve(env.DSH_HOME?.trim() ? env.DSH_HOME : join(homedir(), '.dsh'))
+}
+
+/**
+ * `$DSH_HOME/storages/dsh-restore/`: `pending.json`, shared by every
+ * harness process on this home, and one `live-<pid>.json` per process, which
+ * only that process writes, so two processes never overwrite each other.
+ */
+export function stateDir(env = process.env) {
+  return join(dshHome(env), 'storages', 'dsh-restore')
+}
+
+/**
+ * Read one state file. Missing is `undefined`; a malformed file is reported
+ * and treated as missing, since it only ever holds this plugin's own record.
+ */
+function readRecord(path, warn) {
+  let raw
+  try {
+    raw = readFileSync(path, 'utf8')
+  } catch (error) {
+    if (error.code === 'ENOENT') return undefined
+    throw error
+  }
+  try {
+    const parsed = JSON.parse(raw)
+    if (parsed?.version !== STATE_VERSION) throw new Error(`unsupported version ${parsed?.version}`)
+    return parsed
+  } catch (error) {
+    warn(`dsh-restore: ignoring unreadable ${path}: ${error.message}`)
+    return undefined
+  }
+}
+
+/** Atomic write: a crash mid-write leaves the previous file, never a torn one. */
+function writeRecord(path, value) {
+  mkdirSync(dirname(path), { recursive: true })
+  const tmp = `${path}.${process.pid}.tmp`
+  writeFileSync(tmp, JSON.stringify({ version: STATE_VERSION, ...value }, null, 2))
+  renameSync(tmp, path)
+}
+
+/**
+ * The shared pending set. `scannedThrough` is the newest log time already
+ * offered, so a dismissed crash is not offered again.
+ * @returns {{ pending: Record<string, Entry>, scannedThrough: number }}
+ */
+export function readPending(dir, warn = () => {}) {
+  const record = readRecord(join(dir, 'pending.json'), warn)
+  return { pending: record?.pending ?? {}, scannedThrough: record?.scannedThrough ?? 0 }
+}
+
+/** Serialize shared JSON edits across processes using SQLite's crash-safe writer lock. */
+function withPendingLock(dir, change) {
+  mkdirSync(dir, { recursive: true })
+  const lock = new DatabaseSync(join(dir, 'pending.lock.sqlite'))
+  try {
+    lock.exec('PRAGMA busy_timeout = 5000; BEGIN IMMEDIATE')
+    const result = change()
+    lock.exec('COMMIT')
+    return result
+  } finally {
+    lock.close() // also rolls back and releases the lock if change throws
+  }
+}
+
+/** Read, change and publish the pending set under the same cross-process writer lock. */
+export function updatePending(dir, change, warn = () => {}) {
+  return withPendingLock(dir, () => {
+    const state = readPending(dir, warn)
+    change(state)
+    writeRecord(join(dir, 'pending.json'), state)
+    return state
+  })
+}
+
+/** This machine boot, so a record written before a reboot is known dead; undefined off Linux. */
+function currentBootId() {
+  try {
+    return readFileSync('/proc/sys/kernel/random/boot_id', 'utf8').trim()
+  } catch {
+    return undefined
+  }
+}
+
+/** Whether a process exists (EPERM means it does, owned by someone else). */
+function pidAlive(pid) {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (error) {
+    return error.code === 'EPERM'
+  }
+}
+
+/**
+ * A process's start time in clock ticks since boot (field 22 of
+ * `/proc/<pid>/stat`), which tells a reused pid from the process that first
+ * held it; undefined off Linux or when the process is gone. The fields are read
+ * after the last `)`, since the command name in parentheses may hold spaces.
+ */
+function processStart(pid) {
+  try {
+    const stat = readFileSync(`/proc/${String(pid)}/stat`, 'utf8')
+    return stat.slice(stat.lastIndexOf(')') + 2).split(' ')[19]
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Whether the process that wrote a live record is still running: never when it
+ * carries this process's own pid or another boot's id; else, where procfs
+ * gives start times, only when the pid's process started when the writer did
+ * (a reused pid is another process); otherwise when the pid exists.
+ * @param {{ pid: number, bootId?: string, start?: string }} owner - the record's writer.
+ * @param here - this process's identity and liveness probes.
+ */
+export function ownerAlive(owner, here = { pid: process.pid, bootId: currentBootId(), alive: pidAlive, startOf: processStart }) {
+  if (owner.pid === here.pid) return false
+  if (owner.bootId !== undefined && here.bootId !== undefined && owner.bootId !== here.bootId) return false
+  if (owner.start !== undefined) {
+    const start = here.startOf(owner.pid)
+    if (start !== undefined) return start === owner.start
+  }
+  return here.alive(owner.pid)
+}
+
+/**
+ * Boot step: fold every live record whose process is gone into the shared
+ * pending set (a newer live entry wins) and delete that record. Records of
+ * processes still running are left to them.
+ */
+export function adoptDeadRecords(dir, warn = () => {}, here = undefined) {
+  return withPendingLock(dir, () => {
+    const state = readPending(dir, warn)
+    const adopted = []
+    for (const file of readdirSync(dir)) {
+      if (!/^live-\d+\.json$/u.test(file)) continue
+      const record = readRecord(join(dir, file), warn)
+      if (record !== undefined && ownerAlive(record, here)) continue
+      for (const [id, entry] of Object.entries(record?.live ?? {})) {
+        if ((entry.since ?? 0) >= (state.pending[id]?.since ?? 0)) state.pending[id] = entry
+      }
+      adopted.push(join(dir, file))
+    }
+    writeRecord(join(dir, 'pending.json'), state)
+    // Keep the only recovery record until its replacement has been published.
+    for (const path of adopted) rmSync(path, { force: true })
+    return state
+  })
+}
+
+/**
+ * The JSONL store root, read from its loader row so a moved store is scanned
+ * where it lives. Undefined when the profile persists sessions another way.
+ */
+function jsonlRoot(ctx) {
+  const loader = ctx.get('loader')
+  const row = loader === undefined ? undefined : [...loader.entries()].find(entry => entry.options?.id === 'session-persistence-jsonl')
+  const root = row?.fiber?.config?.root
+  return typeof root === 'string' ? root : undefined
+}
+
+/**
+ * True when a log tail ends in a turn no process closed: the last turn edge is
+ * an open `turn/start`, or the `interrupted` closer the harness writes when a
+ * crashed session is next opened. A clean shutdown closes turns as
+ * `aborted/disposed` instead; the live record covers those.
+ */
+export function endsCutOff(events) {
+  for (let i = events.length - 1; i >= 0; i--) {
+    const { type, data } = events[i]
+    if (type === 'turn/start') return true
+    if (type === 'turn/end') return data?.reason?.kind === 'interrupted'
+  }
+  return false
+}
+
+/** A directory name that is a session id verbatim (the store's path encoding leaves these characters alone). */
+const PLAIN_ID = /^[A-Za-z0-9._-]+$/
+
+/**
+ * Ids of sessions whose stored files changed after `floor`, from file mtimes
+ * under the JSONL store (`<root>/<project>/<session id>/…`). A stat walk costs
+ * milliseconds; opening a log costs a full decode, and an old-format log is
+ * migrated on open, so only these are opened. A missing root lists nothing.
+ */
+export function changedSessionIds(root, floor) {
+  const ids = []
+  let projects
+  try {
+    projects = readdirSync(root, { withFileTypes: true })
+  } catch (error) {
+    if (error.code === 'ENOENT') return ids
+    throw error
+  }
+  for (const project of projects) {
+    if (!project.isDirectory()) continue
+    for (const session of readdirSync(join(root, project.name), { withFileTypes: true })) {
+      if (!session.isDirectory() || !PLAIN_ID.test(session.name)) continue
+      const dir = join(root, project.name, session.name)
+      const newest = Math.max(0, ...readdirSync(dir).map((file) => statSync(join(dir, file)).mtimeMs))
+      if (newest > floor) ids.push(session.name)
+    }
+  }
+  return ids
+}
+
+/**
+ * What the bar shows about a scanned session: its latest title, and whether
+ * its latest goal is still `active` (a clear leaves no goal).
+ */
+export function logFacts(events) {
+  let title
+  let goal = false
+  for (const { type, data } of events) {
+    if (type === 'session/title' && typeof data?.title === 'string') title = data.title
+    if (type === 'goal/change') goal = data?.operation !== 'clear' && data?.goal?.phase === 'active'
+  }
+  return { title, goal }
+}
+
+/** Oldest log time still worth offering: newer than both the last scan and `MAX_CRASH_AGE_MS`. */
+export function crashFloor(after, now = Date.now()) {
+  return Math.max(after, now - MAX_CRASH_AGE_MS)
+}
+
+/**
+ * Pick the cut-off sessions worth offering: newer than what was already
+ * offered (`after`) and than `MAX_CRASH_AGE_MS`. `found` is
+ * `[{ id, cwd, time, title, goal }]` with `time` the log's last event.
+ * @returns {{ entries: Record<string, Entry>, through: number }}
+ */
+export function crashedEntries(found, after, now = Date.now()) {
+  const floor = crashFloor(after, now)
+  const entries = {}
+  let through = after
+  for (const { id, cwd, time, title, goal } of found) {
+    if (time <= floor) continue
+    entries[id] = { cwd, since: time, turn: true, goal, ...(title === undefined ? {} : { title }) }
+    through = Math.max(through, time)
+  }
+  return { entries, through }
+}
+
+/**
+ * Resume one session. Returns the outcome for the bar and whether the entry is
+ * settled (resumed, or gone for good) and can leave the pending set.
+ */
+async function resumeOne(ctx, id) {
+  const resolved = await ctx.sessionController.resolveAgent(id)
+  if ('error' in resolved) {
+    const code = resolved.error?.code ?? 'unknown'
+    // A deleted session or one owned by a subagent runtime never resumes here;
+    // anything else (writer lock held elsewhere, gateway fault) can retry.
+    const settled = code === 'session/not-found' || code === 'session/agent-busy'
+    return { settled, outcome: `skipped: ${code}` }
+  }
+  const { agent } = resolved
+  if (agent.status === 'running') return { settled: true, outcome: 'already running' }
+  const goal = ctx.goals.get(agent)
+  if (goal?.phase === 'active') {
+    try {
+      ctx.goals.resume(agent, { id: goal.id, revision: goal.revision })
+      return { settled: true, outcome: 'goal resumed' }
+    } catch (error) {
+      // Round budget spent, or already armed: fall through to a plain continue.
+      ctx.logger.warn(`dsh-restore: goal resume failed for ${id}: ${error.message}`)
+    }
+  }
+  agent.followup(createUserMessage({
+    content: [{ type: 'text', text: CONTINUE_MESSAGE }],
+    source: { kind: 'restore', form: 'relay' },
+  }))
+  return { settled: true, outcome: 'continued' }
+}
+
+function sendJson(res, status, body) {
+  res.statusCode = status
+  res.setHeader('content-type', 'application/json')
+  res.end(JSON.stringify(body))
+}
+
+/** Read a small JSON body; `undefined` for anything oversized or unparsable. */
+async function readJson(req) {
+  let raw = ''
+  for await (const chunk of req) {
+    raw += chunk
+    if (raw.length > MAX_BODY_BYTES) return undefined
+  }
+  try {
+    return JSON.parse(raw)
+  } catch {
+    return undefined
+  }
+}
+
+export function apply(ctx) {
+  const dir = stateDir()
+  const warn = (text) => ctx.logger.warn(text)
+  adoptDeadRecords(dir, warn)
+
+  // This process's own record: only it writes the file, so another harness on
+  // the same home cannot overwrite it.
+  const livePath = join(dir, `live-${process.pid}.json`)
+  const live = {}
+  const bootId = currentBootId()
+  const start = processStart(process.pid)
+  const saveLive = () => {
+    try {
+      writeRecord(livePath, { pid: process.pid, ...(bootId === undefined ? {} : { bootId }), ...(start === undefined ? {} : { start }), live })
+    } catch (error) {
+      warn(`dsh-restore: cannot write ${livePath}: ${error.message}`)
+    }
+  }
+  saveLive()
+
+  /** Read the shared pending set fresh, apply `change`, write it back. */
+  const changePending = (change) => updatePending(dir, change, warn)
+
+  /**
+   * Find sessions a hard crash cut off, including crashes from before this
+   * plugin was loaded, by reading the tail of every stored log. Recorded
+   * entries win over scanned ones: they know about goals.
+   */
+  const scanLogs = async () => {
+    const found = []
+    let unreadable = 0
+    const root = jsonlRoot(ctx)
+    if (root === undefined) {
+      warn('dsh-restore: no session-persistence-jsonl row, so no boot scan; only the live record is offered')
+      return
+    }
+    const { scannedThrough } = readPending(dir, warn)
+    for (const id of changedSessionIds(root, crashFloor(scannedThrough))) {
+      try {
+        const handle = await ctx.sessionPersistence.open(id, 'read')
+        try {
+          if (handle.header.origin === 'subagent') continue
+          const { events } = await handle.read()
+          if (endsCutOff(events)) found.push({ id, cwd: handle.header.cwd, time: events.at(-1).time, ...logFacts(events) })
+        } finally {
+          await handle.close()
+        }
+      } catch {
+        unreadable += 1
+      }
+    }
+    if (unreadable > 0) warn(`dsh-restore: skipped ${unreadable} session log(s) that could not be read`)
+    const { entries, through } = crashedEntries(found, scannedThrough)
+    changePending((state) => {
+      state.pending = { ...entries, ...state.pending }
+      state.scannedThrough = Math.max(state.scannedThrough, through)
+    })
+  }
+  const scanned = scanLogs().catch((error) => warn(`dsh-restore: log scan failed: ${error.message}`))
+
+  /** Set one flag on a session's live entry; drop the entry once nothing is in flight. */
+  const mark = (session, flag, on) => {
+    if (session.header?.origin === 'subagent') return // the parent resumes its children
+    const entry = live[session.id]
+    if (!on) {
+      if (!entry?.[flag]) return
+      entry[flag] = false
+      if (!entry.turn && !entry.goal) delete live[session.id]
+    } else {
+      if (entry?.[flag]) return
+      live[session.id] = { ...(entry ?? { cwd: session.header?.cwd, since: Date.now() }), [flag]: true }
+    }
+    saveLive()
+  }
+
+  const restore = async () => {
+    const results = []
+    const settled = []
+    for (const id of Object.keys(readPending(dir, warn).pending)) {
+      let result
+      try {
+        result = await resumeOne(ctx, id)
+      } catch (error) {
+        result = { settled: false, outcome: `failed: ${error.message}` }
+      }
+      if (result.settled) settled.push(id)
+      results.push({ id, outcome: result.outcome })
+    }
+    changePending((state) => { for (const id of settled) delete state.pending[id] })
+    return results
+  }
+
+  let restoring
+  const pendingList = () => Object.entries(readPending(dir, warn).pending).map(([id, entry]) => ({ id, ...entry }))
+
+  const handler = async (req, res) => {
+    const rejection = ctx.get('connection')?.requestRejection(req)
+    if (rejection !== undefined) {
+      res.statusCode = rejection
+      res.end()
+      return
+    }
+    // The bar asks once per page load, often before the boot scan finishes.
+    await scanned
+    const method = (req.method ?? 'GET').toUpperCase()
+    if (method === 'GET') {
+      sendJson(res, 200, { pending: pendingList() })
+      return
+    }
+    if (method !== 'POST') {
+      res.setHeader('allow', 'GET, POST')
+      sendJson(res, 405, { message: 'this route answers GET and POST only' })
+      return
+    }
+    // A JSON content type forces a CORS preflight, so another origin cannot
+    // fire a restore with a plain form post.
+    if (!String(req.headers?.['content-type'] ?? '').startsWith('application/json')) {
+      sendJson(res, 415, { message: 'POST a JSON body' })
+      return
+    }
+    const body = await readJson(req)
+    try {
+      if (body?.action === 'dismiss') {
+        changePending((state) => { state.pending = {} })
+        sendJson(res, 200, { results: [], pending: [] })
+        return
+      }
+      if (body?.action === 'restore') {
+        // One restore at a time: a second tab's click joins the running one
+        // instead of sending every session a second `continue`.
+        restoring ??= restore().finally(() => { restoring = undefined })
+        const results = await restoring
+        sendJson(res, 200, { results, pending: pendingList() })
+        return
+      }
+    } catch (error) {
+      sendJson(res, 500, { message: `cannot save recovery state: ${error.message}` })
+      return
+    }
+    sendJson(res, 400, { message: 'action must be "restore" or "dismiss"' })
+  }
+
+  ctx.effect(() => ctx.webServer.register({ kind: 'exact', path: ROUTE, handler }), `restore: ${ROUTE}`)
+
+  ctx.effect(() => {
+    const offEvent = ctx.on('session/event', (session, event) => {
+      if (event?.type === 'turn/start') mark(session, 'turn', true)
+      if (event?.type !== 'turn/end') return
+      // A shutdown disposes running turns; that is exactly the state to keep.
+      const reason = event.data?.reason
+      if (reason?.kind === 'aborted' && reason.reason?.kind === 'disposed') return
+      mark(session, 'turn', false)
+    })
+    const offGoal = ctx.on('goal/activation-changed', ({ sessionId, goal }) => {
+      const session = ctx.sessions.get(sessionId) ?? { id: sessionId }
+      mark(session, 'goal', goal?.activation === 'armed')
+    })
+    return () => {
+      offEvent?.()
+      offGoal?.()
+    }
+  })
+}

package/lib/client.js

@@ -0,0 +1,154 @@
+/**
+ * dsh-restore: browser half.
+ *
+ * A restore bar at the top of the app, like a browser's "didn't shut down
+ * correctly" prompt. It reads the host's pending set once on load from
+ * `GET /restore`; Restore and Dismiss post to the same route. Each listed
+ * session opens on click.
+ *
+ * Plain JavaScript on purpose: the client module system serves this file as a
+ * lazy-CJS factory on `window.__ModuleLoader__`; `react` is provided.
+ */
+
+window.__ModuleLoader__.load({
+  id: '@maci0/dsh-restore',
+
+  factory: (require) => {
+    var module = { exports: {} }
+    var exports = module.exports
+    Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' })
+
+    const React = require('react')
+    const h = React.createElement
+
+    const ROUTE = '/restore'
+
+    // The overlay layer covers the whole window with pointer-events off and
+    // turns them back on for its direct children, so the bar itself is the
+    // child and sizes to its content: a full-width wrapper would eat clicks.
+    const CSS = [
+      '.restore-bar{position:absolute;top:12px;left:50%;transform:translateX(-50%);box-sizing:border-box;max-width:min(640px,calc(100% - 32px));display:flex;flex-direction:column;gap:8px;padding:10px 12px 10px 14px;border:0.5px solid var(--dsw-alias-border-l1);border-radius:12px;background:var(--dsw-specific-tip);box-shadow:0 4px 16px rgba(0,0,0,.12);font-size:13px;color:var(--dsw-alias-label-primary)}',
+      '.restore-row{display:flex;align-items:center;gap:10px}',
+      '.restore-text{flex:1;min-width:0}',
+      '.restore-btn{flex:none;appearance:none;font:inherit;font-size:12px;padding:3px 12px;cursor:pointer;color:var(--dsw-alias-label-primary);background:none;border:1px solid var(--dsw-alias-border-l2);border-radius:999px}',
+      '.restore-btn-primary{border-color:var(--dsw-alias-label-primary);font-weight:500}',
+      '.restore-btn:disabled{cursor:default;opacity:.5}',
+      '.restore-list{margin:0;padding:0;list-style:none;max-height:180px;overflow:auto}',
+      '.restore-item{appearance:none;font:inherit;font-size:12px;background:none;border:0;padding:2px 0;cursor:pointer;color:var(--dsw-alias-label-secondary);text-align:left;width:100%;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}',
+      '.restore-item:hover{color:var(--dsw-alias-label-primary);text-decoration:underline}',
+      '.restore-item:focus-visible,.restore-btn:focus-visible{outline:2px solid var(--dsw-alias-border-l2);outline-offset:2px}',
+    ].join('')
+
+    if (typeof document !== 'undefined') {
+      const style = document.createElement('style')
+      style.textContent = CSS
+      document.head.append(style)
+    }
+
+    /** POST one action and return the parsed body; throws on a non-2xx answer. */
+    const post = async (action) => {
+      const res = await fetch(ROUTE, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', accept: 'application/json' },
+        body: JSON.stringify({ action }),
+      })
+      if (!res.ok) throw new Error(`${ROUTE} answered ${res.status}`)
+      return res.json()
+    }
+
+    const basename = (path) => (path ? path.split(/[\\/]/).filter(Boolean).pop() ?? path : '')
+
+    /** What a pending session is called in the list: its title, else its folder. */
+    const labelOf = (entry, summary) => {
+      const what = entry.goal ? 'goal' : 'turn'
+      return `${entry.title || summary?.title || basename(entry.cwd) || entry.id} · ${what}`
+    }
+
+    const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`
+
+    function RestoreBar({ useSessions, openSession }) {
+      const byId = useSessions((s) => s.byId)
+      const [pending, setPending] = React.useState([])
+      const [busy, setBusy] = React.useState(false)
+      const [open, setOpen] = React.useState(false)
+      const [note, setNote] = React.useState(null)
+      const generation = React.useRef(0)
+
+      React.useEffect(() => {
+        const controller = new AbortController()
+        const load = () => {
+          const started = ++generation.current
+          fetch(ROUTE, { headers: { accept: 'application/json' }, signal: controller.signal })
+            .then((res) => { if (!res.ok) throw new Error(`${ROUTE} answered ${res.status}`); return res.json() })
+            .then((body) => { if (started === generation.current) setPending(Array.isArray(body.pending) ? body.pending : []) })
+            .catch(() => {})
+        }
+        // Re-read when the tab comes back into view: another tab may have
+        // restored or dismissed the set meanwhile.
+        const onVisible = () => { if (document.visibilityState === 'visible') load() }
+        load()
+        if (typeof document !== 'undefined') document.addEventListener('visibilitychange', onVisible)
+        return () => {
+          generation.current += 1
+          controller.abort()
+          if (typeof document !== 'undefined') document.removeEventListener('visibilitychange', onVisible)
+        }
+      }, [])
+
+      if (pending.length === 0) return null
+
+      const act = async (action) => {
+        if (busy) return
+        generation.current += 1
+        setBusy(true)
+        setNote(null)
+        try {
+          // The host answers with whatever it could not settle (a lock held
+          // elsewhere); that stays listed so Restore can be tried again.
+          const { pending: left } = await post(action)
+          generation.current += 1
+          setPending(left)
+          if (left.length > 0) setNote(`${plural(left.length, 'session')} could not be resumed yet.`)
+        } catch (error) {
+          setNote(String(error.message ?? error))
+        } finally {
+          setBusy(false)
+        }
+      }
+
+      return h('div', { className: 'restore-bar', role: 'status' },
+        h('div', { className: 'restore-row' },
+          h('span', { className: 'restore-text' },
+            note ?? `DeepSeek Harness stopped while ${plural(pending.length, 'session')} ${pending.length === 1 ? 'was' : 'were'} still working.`),
+          h('button', {
+            className: 'restore-btn',
+            onClick: () => setOpen(!open),
+            'aria-expanded': open,
+          }, open ? 'Hide' : 'Show'),
+          h('button', { className: 'restore-btn restore-btn-primary', onClick: () => act('restore'), disabled: busy },
+            busy ? '…' : 'Restore'),
+          h('button', { className: 'restore-btn', onClick: () => act('dismiss'), disabled: busy }, 'Dismiss'),
+        ),
+        open && h('ul', { className: 'restore-list' },
+          pending.map((entry) => h('li', { key: entry.id },
+            h('button', { className: 'restore-item', title: entry.cwd, onClick: () => openSession(entry.id) },
+              labelOf(entry, byId?.[entry.id])),
+          )),
+        ),
+      )
+    }
+
+    exports.inject = ['slots', 'uiWorkspace']
+
+    function apply(ctx) {
+      ctx.slots.inject('shell.overlay', () => ctx.slots.register({
+        name: 'shell.overlay',
+        id: 'restore',
+        inject: () => ({ openSession: (id) => ctx.uiWorkspace.openSession(id) }),
+      }, RestoreBar))
+    }
+
+    exports.apply = apply
+    return module.exports
+  },
+})

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Restore",
+    "description": "After a reboot or crash, a bar offers to restore every session that was mid-flight: active goals resume, interrupted turns continue."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "恢复会话",
+    "description": "重启或崩溃后，顶部提示栏可一键恢复所有进行中的会话：继续活跃目标，并让中断的回合继续。"
+  }
+}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@maci0/dsh-restore",
+  "version": "0.8.2",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "type": "module",
+  "main": "index.js",
+  "description": "Browser-style restore bar for DeepSeek Harness: after a reboot or crash, resume goals and continue every session that was mid-flight.",
+  "license": "MIT",
+  "exports": {
+    ".": "./index.js",
+    "./client": {
+      "default": "./lib/client.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./locale/*.json": "./locale/*.json",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-renderer",
+        "@deepseek-ai/dsh-client-ui-layout",
+        "@deepseek-ai/dsh-client-ui-workspace",
+        "@deepseek-ai/dsh-api-session-controller"
+      ]
+    },
+    "compatibility": {
+      "dsh": ">=0.2.0-rc.2 <0.3.0"
+    }
+  },
+  "files": [
+    "icon.svg",
+    "locale/*.json",
+    "index.js",
+    "lib/client.js",
+    "cordis.patch.yml",
+    "README.md",
+    "docs/restore-bar.png",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "bun test",
+    "test:node": "node --test tests/*.test.*"
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/maci0/dsh-restore.git"
+  },
+  "icon": "./icon.svg",
+  "dependencies": {
+    "@deepseek-ai/dsh-llm": "0.2.1-alpha.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "4.0.5-alpha.1"
+  }
+}