@zhengjunyao/dsh-restart 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -4,6 +4,41 @@
 
 ## [Unreleased]
 
+## [0.1.1] - 2026-09-12
+
+就绪判定从「端口应答」改为「端口应答 + 进程存活 + 启动输出无 boot 致命行」。
+
+### 修复 (Fixed)
+
+- **就绪判定不再只看端口**：`dsh web` 先绑端口、后加载插件树，所以「端口应答」不等于
+  「宿主起来了」——2026-09-12 本机真实踩到：一次重启被报成 `ready after 4.0s`，新宿主其实
+  几秒后死于 `plugin tree failed to load … timed out waiting for the writer lock`，页面跳过去
+  才发现是死的。现在判定就绪需同时满足三条：端口应答、进程存活、启动输出里没有 boot 致命行
+  （`plugin tree failed to load`）。
+- **就绪后继续守一段**：新增 `bootWatchMs`（默认 30s）——报了就绪之后助手继续观察新宿主，
+  把它「起来又死」判为启动失败，并撤回 `readyAt`（状态文件不再保留一个已经不存在的就绪声明）；
+  凭证写锁超时这类慢失败（宿主自己的锁等待是 30s）现在是可见的失败，而不是静默的成功。
+- **失败检测保持窄**：致命行只认 boot 阶段必死的输出，不用宽泛的报错正则——健康宿主启动时
+  本来就会打印 `session/list failed` 之类的报错形状噪音，不能因此把好启动判成失败。
+- **observe 模式（launchd 托管）同规**：托管路径原先也是「端口一应答就报就绪」。现在同样要
+  先守住 `readyConfirmMs`，并跟随托管方的日志判断有没有 boot 致命行（宿主进程不在助手手里，
+  日志就是存活性信号）；这里刻意不做长观察——把端口守住是托管方的职责，反过来给托管方
+  自己的重启潮记账只会产生假失败。
+
+### 新增 (Added)
+
+- 新配置项 `readyConfirmMs`（默认 `4000`）与 `bootWatchMs`（默认 `30000`），均为 0 时关闭对应窗口。
+- `tests/helper.mjs` 新增三个用例：宿主应答端口后才在插件上崩掉、应答端口后静默退出、
+  健康宿主打印错误形状噪音（回归保护）。
+- `tests/launchd.mjs` 新增一个用例：observe 模式下托管宿主的日志出现 boot 致命行时不得报就绪。
+
+### 兼容性 (Compatibility)
+
+- DSH：`>=0.1.5-rc.1`
+- Node：`^22.19.0 || >=24.0.0`
+- DSH peer：^0.1.0-rc.6 || ^0.1.1-rc.1 || ^0.1.2-alpha.1 || ^0.1.5-rc.1
+- 无破坏性变更：新增配置项都有默认值，未改动路由、工具名与既有配置语义。
+
 ## [0.1.0] - 2026-09-12
 
 首个版本。

package/README.md

@@ -37,6 +37,12 @@ left. `dsh-restart` handles all three:
 - Failure handling: error lines are detected (Error / EADDRINUSE /
   MODULE_NOT_FOUND / stack frames), the boot log is shown in the overlay, and
   `maxAttempts` (default 2) automatic retries run before giving up.
+- Readiness is not "the port answers": `dsh web` binds its port before the
+  plugin tree loads, so the helper only reports ready once the port answers,
+  the process is still alive, and the boot output carries no fatal line — held
+  over `readyConfirmMs` (4s) first, then watched for `bootWatchMs` (30s) so a
+  host that reports ready and dies seconds later is reclassified as a failed
+  restart instead of a silent success.
 - Agent tools: `dsh_restart_status` (read-only) and `dsh_restart`, which demands
   `confirm: true` because the local standing rule is that DSH is never restarted
   without explicit user consent.
@@ -91,7 +97,7 @@ panel / dsh_restart
 ## Tests
 
 ```sh
-pnpm test    # 129 assertions across five suites
+pnpm test    # 168 assertions across five suites
 ```
 
 `smoke` (config/history/log detection/host identity), `helper` (the real helper

package/README.zh.md

@@ -40,6 +40,14 @@
   报错行、退出码，并可一键「重试启动」。
 - **失败自动重试**：`maxAttempts`（默认 2）次内自动重试；都失败就停在那里等人工处理，
   不会把端口/日志丢掉。
+- **就绪不等于端口通了**：`dsh web` 会先绑端口、后加载插件树，所以「端口应答」远早于
+  「宿主真的起来了」。助手判定就绪要同时满足三条——端口应答、进程存活、启动输出里没有
+  boot 致命行——并先守住 `readyConfirmMs`（默认 4s）；此后还会继续观察
+  `bootWatchMs`（默认 30s），把「已经报了就绪、几秒后却自己死掉」的启动（例如凭证写锁
+  等 30 秒才超时）重新判为失败，而不是留下一个假的成功。
+  **launchd 托管的 observe 模式同规**：先守 `readyConfirmMs`，并跟随托管方日志判断有没有
+  boot 致命行（宿主进程不在助手手里，日志就是存活性信号）；托管路径刻意不做长观察——
+  守住端口是托管方的职责。
 - **Agent 工具**：`dsh_restart_status`（只读：宿主 pid/端口/版本/启动时长/启动命令、
   助手阶段与失败原因、最近重启记录、上次启动日志里的疑似报错行）、
   `dsh_restart`（真正重启；**必须已获得用户同意**并传 `confirm: true`，
@@ -85,6 +93,8 @@ dsh plugin --profile web add github:zhengjy01/dsh-restart
 | `killGraceMs` | `6000` | 端口迟迟不释放时，助手 SIGKILL 旧进程前的宽限 |
 | `portFreeTimeoutMs` | `25000` | 等旧进程释放端口的上限 |
 | `lingerMs` | `4000` | 就绪后助手退出前保留控制台的时间 |
+| `readyConfirmMs` | `4000` | 端口应答后、判定「已就绪」前必须守住的稳定时长（0 = 不守） |
+| `bootWatchMs` | `30000` | 已报就绪后继续观察新宿主、把「起来又死」改判为失败的时间窗（0 = 不守） |
 | `logLines` | `200` | 面板/接口返回的日志行数 |
 | `autoReload` | `true` | 新宿主应答后自动刷新页面 |
 | `showOverlay` | `true` | 重启时显示全屏遮罩 |
@@ -136,18 +146,21 @@ dsh plugin --profile web add github:zhengjy01/dsh-restart
 ## 测试
 
 ```sh
-pnpm test        # 129 项断言，五个套件
+pnpm test        # 168 项断言，五个套件
 ```
 
 - `tests/smoke.mjs` — 配置读写与钳制、历史、日志尾部与报错识别、启动签名、宿主信息；
 - `tests/helper.mjs` — **真的**跑助手：崩溃路径（捕获退出码、stderr 报错行、控制台页面、
-  手动重试）与成功路径（等端口 → 拉起 → 就绪计时）；
+  手动重试）、成功路径（等端口 → 拉起 → 就绪计时），以及就绪判定的三种边界：
+  宿主应答端口后才在插件上崩掉（不得报就绪，且要撤回已报的就绪状态、写入失败报告）、
+  应答端口后静默退出（没有任何报错行也要靠存活性判失败）、健康宿主打印错误形状的噪音
+  （不得误判为失败）；
 - `tests/routes.mjs` — 合成的 req/res 打全部路由，含 loopback/跨站/方法守卫；
 - `tests/handoff.mjs` — 端到端：假宿主进程 → POST 重启 → 旧进程真的退出 →
   助手用相同命令拉起第二代 → 端口重新应答（新 pid）、`restarted: true`、历史落盘；
 - `tests/launchd.mjs` — launchd 识别（**按 pid 匹配 `launchctl list`**，因为 Node 会把
   `XPC_SERVICE_NAME` 改写成 `0`）+ observe 模式（助手执行 kickCommand、跟随托管方日志、
-  **绝不自己 spawn**）。
+  **绝不自己 spawn**），以及托管宿主日志出现 boot 致命行时不得报就绪。
 
 ## 边界
 

package/helper/restart-helper.mjs

@@ -87,6 +87,22 @@ const PORT_FREE_TIMEOUT_MS = Number(spec.portFreeTimeoutMs) || 25_000
 const MAX_ATTEMPTS = Math.max(1, Number(spec.maxAttempts) || 2)
 const RING_LINES = Math.max(200, Number(spec.ringLines) || 600)
 const LINGER_MS = Math.max(0, Number(spec.lingerMs) || 4_000)
+/**
+ * How long a boot that answers the port must hold before readiness is
+ * reported. The port answering is not the same event as the host being up:
+ * `dsh web` binds it before the plugin tree loads, so this window is what
+ * separates "listening" from "survived the first seconds of its boot".
+ */
+const READY_CONFIRM_MS = Math.max(0, Number(spec.readyConfirmMs) || 4_000)
+/**
+ * How long a host that already reported ready is still watched before the
+ * helper lets go of it. Boot failures that wait on something slow surface long
+ * after the port answers — a credentials writer-lock timeout is 30s — so
+ * without this window a restart can be reported ready seconds before the new
+ * host dies, which is exactly the silent-success case this helper exists to
+ * prevent.
+ */
+const BOOT_WATCH_MS = Math.max(0, Number(spec.bootWatchMs) || 30_000)
 /**
  * `spawn` (default): this helper relaunches the host itself.
  * `observe`: something else owns the relaunch (a launchd job, a supervisor);
@@ -139,11 +155,24 @@ const ERROR_HINT = new RegExp(
   ].join('|'),
 )
 
+/**
+ * Boot-stage output no live host keeps running after.
+ *
+ * Deliberately narrow, and deliberately not {@link ERROR_HINT}: a healthy
+ * `dsh web` prints error-shaped lines all through its boot (`session/list
+ * failed`, a plugin warning, a retrying network call), and treating those as
+ * fatal would turn healthy restarts into failed ones. Only lines that mean the
+ * host is on its way out belong here.
+ */
+const FATAL_BOOT_HINT = /plugin tree failed to load/
+
 /** Append one line to the log file and the in-memory ring. */
 function record(line, stream = 'out') {
   const text = String(line).replace(ANSI, '')
   const at = Date.now()
-  ring.push({ t: at, s: stream, text })
+  // The attempt number rides along so a fatal line from a boot we already gave
+  // up on cannot condemn the attempt that is running now.
+  ring.push({ t: at, s: stream, text, attempt })
   if (ring.length > RING_LINES) ring.splice(0, ring.length - RING_LINES)
   // Only the host's own output can explain a failed boot; our 'sys' lines are
   // narration and would otherwise trip the detector on their own wording.
@@ -168,6 +197,22 @@ function makeLineSplitter(stream) {
   }
 }
 
+/**
+ * The newest boot-fatal line the host printed, or null.
+ *
+ * Read from the ring rather than from `errors`: that list carries everything
+ * that looks like an error to a human, including lines a healthy host prints
+ * on the way up. Our own narration is skipped — it says "failed" a lot.
+ */
+function fatalBootLine() {
+  for (let index = ring.length - 1; index >= 0; index -= 1) {
+    const line = ring[index]
+    if (line.attempt !== attempt) continue
+    if (line.s !== 'sys' && FATAL_BOOT_HINT.test(line.text)) return line.text
+  }
+  return null
+}
+
 /** Fallback port actually bound (null until the console is listening). */
 let activeFallbackPort = null
 
@@ -324,6 +369,61 @@ async function waitPortReady(port, host, timeoutMs, child) {
   }
 }
 
+/**
+ * Watch a boot that already answers the port.
+ *
+ * Three things end the watch early, and each of them means the new host is not
+ * the host the caller was promised: the process is gone, its output printed a
+ * line nothing survives, or the port stopped answering.
+ *
+ * @param child - the launched host, or null when we do not own it.
+ * @param windowMs - how long the boot has to hold.
+ * @returns the failure to report, or null when the host survived the window.
+ */
+async function watchBoot(child, windowMs) {
+  const deadline = Date.now() + windowMs
+  for (;;) {
+    const fatal = fatalBootLine()
+    if (fatal !== null) return { kind: 'boot', message: `启动输出报错：${fatal}` }
+    if (child !== null && child.exitCode !== null) {
+      const tail = errors.slice(-3).map((entry) => entry.text).join(' | ')
+      return {
+        kind: 'exit',
+        message: `新进程退出（code=${child.exitCode}）${tail === '' ? '' : '：' + tail}`,
+        exitCode: child.exitCode,
+      }
+    }
+    if (!(await portOpen(PORT, HOST))) {
+      return { kind: 'port', message: `新进程不再占用 ${URL_BASE}` }
+    }
+    if (Date.now() >= deadline) return null
+    await sleep(300)
+  }
+}
+
+/**
+ * Decide whether a boot that answers the port is really up.
+ *
+ * Two windows, because a `dsh` boot fails at two speeds. The settle window
+ * catches the fast ones (a plugin that cannot be imported, a module that is not
+ * there) before readiness is ever claimed. The watch that follows catches the
+ * late ones — a boot blocked on a lock or a slow plugin load looks healthy for
+ * tens of seconds first — and clears `readyAt` again, so the status file never
+ * keeps claiming a host that has since died.
+ *
+ * @returns null when the boot is confirmed, or the failure to report.
+ */
+async function confirmBoot(child) {
+  const early = await watchBoot(child, READY_CONFIRM_MS)
+  if (early !== null) return early
+  readyAt = Date.now()
+  setPhase('ready', `ready after ${((readyAt - startedAt) / 1000).toFixed(1)}s`)
+  const late = await watchBoot(child, BOOT_WATCH_MS)
+  if (late === null) return null
+  readyAt = null
+  return late
+}
+
 // --------------------------------------------------------------- child spawn
 
 /** Launch the new host, wiring both output streams into the log. */
@@ -667,6 +767,17 @@ async function observeBoot() {
   for (;;) {
     follow()
     if (await portOpen(PORT, HOST)) {
+      // The owner's new host answers — but an answering port is not a host
+      // either here: the same "listening, then dead on a plugin" boot happens
+      // under launchd. Observe mode has no child handle, so the owner's log is
+      // the liveness signal.
+      const settled = await observeSettle(follow)
+      if (settled !== null) {
+        failure = settled
+        record(`[dsh-restart] attempt ${attempt} failed: ${failure.message}`, 'sys')
+        persist()
+        return 'failed'
+      }
       readyAt = Date.now()
       setPhase('ready', `ready after ${((readyAt - startedAt) / 1000).toFixed(1)}s`)
       return 'ready'
@@ -684,6 +795,29 @@ async function observeBoot() {
   }
 }
 
+/**
+ * Hold an owner-managed boot through the settle window.
+ *
+ * No long watch here, deliberately: keeping the port up is the owner's job, and
+ * a supervisor that restarts a flapping host would otherwise leave one failure
+ * in the log for this helper to wrongly pin on the restart it was asked to
+ * watch.
+ *
+ * @param follow - the owner-log tailer, pumped each pass so late lines land.
+ * @returns the failure to report, or null when the boot held.
+ */
+async function observeSettle(follow) {
+  const deadline = Date.now() + READY_CONFIRM_MS
+  for (;;) {
+    follow()
+    const fatal = fatalBootLine()
+    if (fatal !== null) return { kind: 'boot', message: `启动输出报错：${fatal}` }
+    if (!(await portOpen(PORT, HOST))) return { kind: 'port', message: `新进程不再占用 ${URL_BASE}` }
+    if (Date.now() >= deadline) return null
+    await sleep(300)
+  }
+}
+
 /** One launch attempt; resolves 'ready' | 'failed'. */
 async function attemptBoot() {
   if (MODE === 'observe') return observeBoot()
@@ -695,9 +829,12 @@ async function attemptBoot() {
   }
   setPhase('waiting-ready', `waiting for ${URL_BASE} to answer (up to ${Math.round(BOOT_TIMEOUT_MS / 1000)}s)`)
   if (await waitPortReady(PORT, HOST, BOOT_TIMEOUT_MS, child)) {
-    readyAt = Date.now()
-    setPhase('ready', `ready after ${((readyAt - startedAt) / 1000).toFixed(1)}s`)
-    return 'ready'
+    const late = await confirmBoot(child)
+    if (late === null) return 'ready'
+    failure = late
+    record(`[dsh-restart] attempt ${attempt} failed: ${failure.message}`, 'sys')
+    persist()
+    return 'failed'
   }
   const code = child.exitCode
   const tail = errors.slice(-3).map((entry) => entry.text).join(' | ')

package/lib/index.js

@@ -31,6 +31,8 @@ const DEFAULT_CONFIG = {
 	killGraceMs: 6e3,
 	portFreeTimeoutMs: 25e3,
 	lingerMs: 4e3,
+	readyConfirmMs: 4e3,
+	bootWatchMs: 3e4,
 	logLines: 200,
 	autoReload: true,
 	showOverlay: true,
@@ -102,6 +104,8 @@ function normalizeConfig(patch, base = DEFAULT_CONFIG) {
 		killGraceMs: intIn(source.killGraceMs ?? base.killGraceMs, base.killGraceMs, 0, 12e4),
 		portFreeTimeoutMs: intIn(source.portFreeTimeoutMs ?? base.portFreeTimeoutMs, base.portFreeTimeoutMs, 0, 3e5),
 		lingerMs: intIn(source.lingerMs ?? base.lingerMs, base.lingerMs, 0, 6e5),
+		readyConfirmMs: intIn(source.readyConfirmMs ?? base.readyConfirmMs, base.readyConfirmMs, 0, 12e4),
+		bootWatchMs: intIn(source.bootWatchMs ?? base.bootWatchMs, base.bootWatchMs, 0, 6e5),
 		logLines: intIn(source.logLines ?? base.logLines, base.logLines, 20, 2e3),
 		autoReload: typeof source.autoReload === "boolean" ? source.autoReload : base.autoReload,
 		showOverlay: typeof source.showOverlay === "boolean" ? source.showOverlay : base.showOverlay,
@@ -572,6 +576,8 @@ async function buildSpec(options) {
 		killGraceMs: options.config.killGraceMs,
 		portFreeTimeoutMs: options.config.portFreeTimeoutMs,
 		lingerMs: options.config.lingerMs,
+		readyConfirmMs: options.config.readyConfirmMs,
+		bootWatchMs: options.config.bootWatchMs,
 		ringLines: options.config.logLines,
 		dshVersion: await readDshVersion(),
 		profile: readProfile(),

package/lib/types/config.d.ts

@@ -36,6 +36,18 @@ export interface RestartConfig {
     portFreeTimeoutMs: number;
     /** How long the helper keeps its console up after success before exiting. */
     lingerMs: number;
+    /**
+     * How long a boot that answers the port must hold before the helper reports
+     * it ready. `dsh web` binds its port before the plugin tree loads, so this is
+     * what separates "listening" from "survived the start of its boot".
+     */
+    readyConfirmMs: number;
+    /**
+     * How long the helper keeps watching a host that already reported ready.
+     * Boot failures that wait on something slow (a credentials writer-lock
+     * timeout is 30s) surface well after the port answers.
+     */
+    bootWatchMs: number;
     /** Lines of boot log kept for display. */
     logLines: number;
     /** Auto-reload the page once the new host answers. */

package/lib/types/restart.d.ts

@@ -111,6 +111,8 @@ export interface RestartSpec {
     killGraceMs: number;
     portFreeTimeoutMs: number;
     lingerMs: number;
+    readyConfirmMs: number;
+    bootWatchMs: number;
     ringLines: number;
     dshVersion: string;
     profile: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhengjunyao/dsh-restart",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "One-click restart for DeepSeek Harness: a web button (plus a dsh_restart agent tool) hands the relaunch to a detached helper that waits for the port to free, relaunches the exact same command, streams the new host's output, auto-reconnects the page — and shows the boot errors in a recovery console when the new host dies",
   "type": "module",
   "main": "lib/index.js",