dsh-deeppilot 0.9.2 → 0.9.3

package/docs/DSH_RELEASE_MEMORY.md

@@ -29,16 +29,32 @@
 - **Protocol verdict:** no required DeepPilot phone-protocol break. Protocol v2,
   pairing state, and device records are unchanged; already-paired phones need no
   action.
-- **Release verdict (`0.9.2`, shipped 2026-10-04):** `scripts/smoke-live.mts`
-  was run against a live **`dsh-v0.2.1-alpha.1`** web profile and passed with
-  **0 failures**. This is the first live-host verification since the 0.9.1
-  entry, and it retires the gate that entry left open ("pending separate
-  authorization before the `0.9.1` release ships") — on a newer host than the
+- **Release verdict (`0.9.2`, published 2026-10-05, tag `v0.9.2` @ `4b43671`):**
+  shipped to `latest`. Verified on the registry: version present, `dist-tags.latest`
+  moved off `0.9.1`, `gitHead` `4b436715` matches the tag and HEAD, 65 files,
+  and a clean DSH profile install of `dsh-deeppilot@0.9.2` composes with the
+  plugin's three `cordis.patch.yml` entries present and no missing-module error.
+  `scripts/smoke-live.mts` passed with **0 failures** against a live
+  **`dsh-v0.2.1-alpha.1`** web profile — the first live-host verification since
+  the 0.9.1 entry, retiring the gate it left open ("pending separate
+  authorization before the `0.9.1` release ships"), on a newer host than the
   rc.2 that entry contemplated, which is strictly stronger evidence: the
   `0.2.1-alpha.1` source-diff above found zero changed `src/` files across all
   12 peer packages, and the live run agrees. The plugin's own build and type
-  baselines stay pinned to `0.2.0-rc.2`; nothing about the pin changed for this
-  release.
+  baselines stay pinned to `0.2.0-rc.2`; nothing about the pin changed.
+  - **Install caveat users will hit — DSH's release-age policy.** On a clean
+    profile, `dsh plugin add dsh-deeppilot` installed **`0.9.1`**, not the just
+    published `0.9.2`, even though `latest` already pointed at `0.9.2`. DSH
+    deliberately prefers a slightly older release and offers an exact-version
+    path instead; `dsh plugin add dsh-deeppilot@0.9.2` installs the new one.
+    This is expected DSH behaviour, not a publishing failure — do not read the
+    older version in the installer as a broken release.
+  - **Peer-range note for future audits.** `evaluatePluginCompatibility` checks
+    each peer against the *running DSH version*, but `cordis` and `schemastery`
+    are host-vendored third parties and `react` comes from the Web app. Judging
+    those three against a DSH version number reports false mismatches. They are
+    also `optional` in `peerDependenciesMeta`. Confirm installability by
+    composing a real profile, not by iterating the peer table.
 - **Two tracked follow-ups:**
   1. **Schedule documentation is now stale.** Automation tasks became a
      built-in Web capability and `@deepseek-ai/dsh-experimental-schedule-bundle`
@@ -201,6 +217,31 @@ in the same class as the other input-shaped Schedule refusals. Without the
 mapping `wireErrorOf` falls through to `WIRE_ERROR_FALLBACK` (`E_INTERNAL`), which
 would tell the client the failure was worth retrying.
 
+### Cross-platform trap found while shipping 0.9.2
+
+CI's `plugin` job hung on `npm test` four times while shipping 0.9.2. Worth
+recording because macOS could never reproduce it and the fix is one line each.
+
+`tests/journal-parity.test.ts` used `join('/proc/definitely/not/writable', …)`
+as its "unwritable path" probe, in two places. `/proc` is a Linux-only pseudo
+filesystem: on macOS the path simply does not exist, so the branch had only ever
+been exercised on macOS and had never run on Linux at all. On Linux, writing
+under `/proc` does not return an error — and because `dispatch-journal`'s
+`save()` is entirely synchronous `fs` calls (`mkdirSync`/`openSync`/
+`writeFileSync`/`fsyncSync`/`renameSync`), a single write blocks the whole event
+loop. Even `setTimeout` stops firing, and node's `--test-timeout` can only report
+a file-level timeout. Both sites now build the unwritable target inside the
+scratch directory (a file-with-a-child shape that yields `ENOTDIR` identically on
+every platform); recorded values are unchanged because all three candidate paths
+returned the same status on macOS.
+
+Two lessons for future audits: the workflow sets no `timeout-minutes`, so a hang
+costs the full 6-hour default before failing — cancel and re-run rather than
+waiting; and reproduce Linux-only behaviour in a container instead of inferring
+it. `docker run --rm --cpus=2 -v $PWD:/app -w /app node:22` matches the runner
+closely enough (2 cores, and the same `v22.23.x` that `node-version: 22` floats
+to).
+
 ### Re-audit procedure used
 
 Same blobless-clone method as the rc.2 and rc.1 entries, with two refinements:

package/lib/index.d.ts

@@ -59,7 +59,7 @@ type DispatchOutcome =
 {
   kind: 'mismatch';
 } |
-/** 文件损坏 / 目录不可造，journal 已降级。 */
+/** 构造期解析失败：journal 已永久降级，本次进程不再投递。 */
 {
   kind: 'unavailable';
 } |
@@ -81,7 +81,10 @@ type DispatchOutcome =
 {
   kind: 'crashed';
 } |
-/** 预留条目时写盘失败。 */
+/**
+ * 预留条目时落盘失败——上游**没有**被调用，但无从判断 rename 是否已经
+ * 生效（save() 可能在 rename 之后才抛），因此条目留在内存里按 unknown 处理。
+ */
 {
   kind: 'reserve-failed';
 } |
@@ -125,12 +128,26 @@ interface DispatchJournalOptions<TRequest = unknown, TResult = unknown> {
    * mutation 否（重复方立刻拿到 unknown → E_INTERNAL）。两者都由对等快照钉住。
    */
   joinInFlight?: boolean;
+  /**
+   * 落盘失败的诊断输出。由调用方注入它已有的 logger；缺省即静默。
+   * 只打阶段与 errno，绝不打条目内容或消息体（plugin 的日志禁令）。
+   */
+  log?: (message: string) => void;
+  /**
+   * 目录 fsync 里「对 fd 调用 fsync」这一步的覆盖点，缺省即 `fsyncSync`。
+   *
+   * 存在的唯一理由是可测：Linux CI 上复现不出 Windows 的 EPERM。注入点刻意
+   * 停在 fd 这一层而不是替换整个目录 fsync——容忍 EPERM 的判断必须留在真实
+   * 路径里被测到，换掉整函数就等于把待测逻辑一起换掉了。
+   */
+  fsyncFileDescriptor?: (fd: number) => void;
 }
 /** Durable at-most-once dispatch. Unknown outcomes are never automatically retried. */
 declare class DispatchJournal<TRequest = unknown, TResult = unknown> {
   private readonly options;
   private entries;
   private inFlight;
+  /** 只由构造期的解析失败置位，见下方 catch；运行期落盘失败不碰它。 */
   private healthy;
   private readonly maxFileBytes;
   private readonly capacity;
@@ -141,6 +158,15 @@ declare class DispatchJournal<TRequest = unknown, TResult = unknown> {
   /** id 的纪元前缀是否还在保留窗口内（未来 5 分钟以上同样算非法）。 */
   private expired;
   private save;
+  /**
+   * 落盘一次，失败只报不降级。
+   *
+   * 与 `healthy` 的分工：`healthy` 只由构造期的解析失败置位，运行期的磁盘错误
+   * 不再拉黑整个进程——此前一次 save() 失败就让本进程余下的所有投递永久返回
+   * unknown，直到 DSH 重启（issue #20 / #26）。现在只影响当次投递，下一次
+   * dispatch 会重新尝试。
+   */
+  private persist;
   /** 查询既有回执；`request` 交给 codec 的 matches 判定（缺省即不提供 lookup）。 */
   lookup(deviceId: string, id: string, request?: unknown): TResult | undefined;
   /**
@@ -797,6 +823,8 @@ type ScheduleBridgeResult<T> = {
 declare class HostBridge {
   private readonly apiProxy;
   private readonly historyBufferMax;
+  /** 三个 journal 的落盘失败诊断输出；缺省即静默。不打任何消息体。 */
+  private readonly log?;
   readonly id: number;
   private summaries;
   private activeTools;
@@ -820,7 +848,9 @@ declare class HostBridge {
   }, DeliveryReceipt>;
   readonly scheduleMutations: DispatchJournal<unknown, MutationDispatchResult<unknown>>;
   readonly forkMutations: DispatchJournal<unknown, MutationDispatchResult<unknown>>;
-  constructor(apiProxy: ApiProxyLike, historyBufferMax?: number, deliveryJournalPath?: string, scheduleJournalPath?: string, forkJournalPath?: string);
+  constructor(apiProxy: ApiProxyLike, historyBufferMax?: number, deliveryJournalPath?: string, scheduleJournalPath?: string, forkJournalPath?: string,
+  /** 三个 journal 的落盘失败诊断输出；缺省即静默。不打任何消息体。 */
+  log?: ((message: string) => void) | undefined);
   private pushOutlet;
   private widgetFingerprint;
   /**

package/lib/index.js

@@ -47,6 +47,21 @@ const ERROR_CODES = {
 const WIRE_ERROR_FALLBACK = "E_INTERNAL";
 const DOMAIN_TABLES = {
 	session: {
+		"session/not-found": "E_NOT_FOUND",
+		"workspace/not-found": "E_NOT_FOUND",
+		"session/agent-busy": "E_BUSY",
+		"session/writer-held": "E_BUSY",
+		"session/conflict": "E_BUSY",
+		"workspace/session-active": "E_BUSY",
+		"gateway/bad-request": "E_PROTOCOL",
+		"session/title-invalid": "E_PROTOCOL",
+		"session/attachment-invalid": "E_PROTOCOL",
+		"session/invalid-time-zone": "E_PROTOCOL",
+		"workspace/invalid-path": "E_PROTOCOL",
+		"workspace/name-conflict": "E_PROTOCOL",
+		"workspace/move-invalid": "E_PROTOCOL",
+		"workspace-file/not-found": "E_NOT_FOUND",
+		"directory-picker/unavailable": "E_UNSUPPORTED",
 		"session-not-found": "E_NOT_FOUND",
 		"workspace-not-found": "E_NOT_FOUND",
 		"agent-busy": "E_BUSY",
@@ -60,6 +75,11 @@ const DOMAIN_TABLES = {
 		"directory-picker-unavailable": "E_UNSUPPORTED"
 	},
 	model: {
+		"session/not-found": "E_NOT_FOUND",
+		"session/agent-busy": "E_BUSY",
+		"session/writer-held": "E_BUSY",
+		"session/conflict": "E_BUSY",
+		"session/model-unavailable": "E_NOT_FOUND",
 		"session-not-found": "E_NOT_FOUND",
 		"agent-busy": "E_BUSY",
 		"session-conflict": "E_BUSY",
@@ -80,18 +100,55 @@ const DOMAIN_TABLES = {
 		"subagent_session": "E_PROTOCOL"
 	}
 };
+/**
+* 剥掉 `namespace/` 前缀：`session/agent-busy` -> `agent-busy`。
+*
+* DSH 的 API 层现在抛的是带命名空间的码（`session/agent-busy`、
+* `workspace/not-found`、`gateway/internal`……），而下面的表一开始只有扁平写法。
+* 两边对不上时整表失配、一律落进 `E_INTERNAL`，于是 `E_BUSY` 永远出不来——
+* 而 `E_BUSY` 正是客户端决定「该不该重试」的那个码（issue #26）。
+*/
+function canonicalHostCode(code) {
+	const slash = code.lastIndexOf("/");
+	return slash === -1 ? code : code.slice(slash + 1);
+}
+/** 查表顺序：原样命中优先，其次剥掉命名空间后命中，最后才是兜底。 */
+function lookupCode(domain, code) {
+	const table = DOMAIN_TABLES[domain];
+	return table[code] ?? table[canonicalHostCode(code)] ?? "E_INTERNAL";
+}
 /** 一个 Host 失败翻译成 Bridge 的失败结果：直接携带 wire 错误码。 */
 function wireErrorOf(domain, error) {
+	const code = lookupCode(domain, error.code);
 	return {
 		ok: false,
-		code: DOMAIN_TABLES[domain][error.code] ?? "E_INTERNAL",
-		message: error.message ?? error.code
+		code,
+		message: describeFailure(error, code)
 	};
 }
+/**
+* 组装给手机看的那句话。
+*
+* DSH 把 prompt 准入的**任意**内部失败包成 `session/agent-busy`，真实原因只留在
+* `details.reason`（`@deepseek-ai/dsh-api-session-controller` 的 `types/commands.js`
+* 里那一句 `throw new RemoteError('session/agent-busy', 'prompt rejected', { reason: … })`）。
+* 插件原先只取 `message`，于是手机端永远只显示笼统的「发送未确认」。
+*
+* 只在落到 `E_INTERNAL` 时追加 reason：这类码按定义对客户端没有可执行含义，
+* 多这一句不改变「该不该重试」的判断，却能让用户和排查者看到真正的原因。已映射
+* 的码本身已经可执行，保持原样不动。
+*/
+function describeFailure(error, wireCode) {
+	const base = error.message ?? error.code;
+	if (wireCode !== "E_INTERNAL") return base;
+	const reason = error.details?.reason;
+	if (typeof reason !== "string" || reason.length === 0) return base;
+	return `${base} (${error.code}): ${reason}`;
+}
 /** 只有一个 Host code（没有附带 message）时取它的 wire 码。 */
 function wireCodeFor(domain, hostCode) {
 	if (hostCode === void 0) return WIRE_ERROR_FALLBACK;
-	return DOMAIN_TABLES[domain][hostCode] ?? "E_INTERNAL";
+	return lookupCode(domain, hostCode);
 }
 function pendingResponseErrorCode(reason) {
 	switch (reason) {
@@ -4720,6 +4777,11 @@ function createRemoteTransport(deps) {
 * 核心拥有：key 派生、原子写盘（temp + fsync + rename + 目录 fsync）、加载与
 * 逐字段校验、保留清扫、容量、healthy 降级、在途去重、opener 单例。
 *
+* healthy 的唯一来源是**构造期的解析失败**（文件损坏，续写会写坏格式）；
+* 运行期的落盘失败只影响当次投递，下次投递重新尝试落盘。两者曾经共用同一个
+* 标志位，一次瞬时磁盘错误就让整个进程的所有投递永久短路到 DSH 重启
+* （issue #20 / #26）。
+*
 * codec 拥有：一次投递的全部「方言」。它同时是两个 adapter——prompt 回执与
 * mutation 结果——因此这条缝是真的，不是假想的。
 */
@@ -4727,11 +4789,51 @@ const DEFAULT_CAPACITY = 1e4;
 const DEFAULT_RETENTION_MS = 6048e5;
 /** 比保留窗口多宽限 5 分钟：边界附近的条目不会被反复删了又写。 */
 const SWEEP_GRACE_MS = 3e5;
+/**
+* 目录 fsync 的三个「平台不支持」码。
+*
+* Windows 上 `openSync(dir, 'r')` 成功但 `fsyncSync(dirfd)` 必定抛错（社区实测
+* 报 EPERM，issue #20 / #26）；EISDIR / EINVAL 是同一现象的其他平台变体。
+* 这三个码在本调用点都不代表数据损坏：文件内容已在 rename 之前 fsync 过，且
+* rename 在同一目录内是原子的，跳过的只是目录项的额外耐久性保证。
+*/
+const TOLERATED_DIR_FSYNC_CODES = /* @__PURE__ */ new Set([
+	"EPERM",
+	"EISDIR",
+	"EINVAL"
+]);
+/** errno 优先，取不到就退回错误本身的字符串（诊断用，不参与控制流）。 */
+function errnoOf(error) {
+	const code = error?.code;
+	return typeof code === "string" ? code : String(error);
+}
+/** 这类错误是否属于「该平台不支持目录 fsync」而非真的写坏了。 */
+function isToleratedDirectoryFsyncError(error) {
+	return TOLERATED_DIR_FSYNC_CODES.has(errnoOf(error));
+}
+/**
+* 目录 fsync：把 rename 造成的目录项变更推给磁盘。
+*
+* 按 errno 而非 `process.platform` 判断：WSL / Wine 之类环境下平台名并不可靠，
+* 而 errno 才是真正决定「这个平台支不支持」的信号（issue #26 给的两种建议里，
+* 按 errno 的那种才是对的）。其余 errno（EIO、ENOSPC……）照旧抛出。
+*/
+function fsyncDirectory(dirPath, fsync = fsyncSync) {
+	const fd = openSync(dirPath, "r");
+	try {
+		fsync(fd);
+	} catch (error) {
+		if (!isToleratedDirectoryFsyncError(error)) throw error;
+	} finally {
+		closeSync(fd);
+	}
+}
 /** Durable at-most-once dispatch. Unknown outcomes are never automatically retried. */
 var DispatchJournal = class {
 	options;
 	entries = Object.create(null);
 	inFlight = /* @__PURE__ */ new Map();
+	/** 只由构造期的解析失败置位，见下方 catch；运行期落盘失败不碰它。 */
 	healthy = true;
 	maxFileBytes;
 	capacity;
@@ -4782,11 +4884,23 @@ var DispatchJournal = class {
 			closeSync(fd);
 		}
 		renameSync(temp, path);
-		const dir = openSync(dirname(path), "r");
+		fsyncDirectory(dirname(path), this.options.fsyncFileDescriptor);
+	}
+	/**
+	* 落盘一次，失败只报不降级。
+	*
+	* 与 `healthy` 的分工：`healthy` 只由构造期的解析失败置位，运行期的磁盘错误
+	* 不再拉黑整个进程——此前一次 save() 失败就让本进程余下的所有投递永久返回
+	* unknown，直到 DSH 重启（issue #20 / #26）。现在只影响当次投递，下一次
+	* dispatch 会重新尝试。
+	*/
+	persist() {
 		try {
-			fsyncSync(dir);
-		} finally {
-			closeSync(dir);
+			this.save();
+			return true;
+		} catch (error) {
+			this.options.log?.("journal 落盘失败，本次投递按未确认处理，下次投递会重新尝试：" + errnoOf(error));
+			return false;
 		}
 	}
 	/** 查询既有回执；`request` 交给 codec 的 matches 判定（缺省即不提供 lookup）。 */
@@ -4831,12 +4945,7 @@ var DispatchJournal = class {
 			...codec.reserve(request, id)
 		};
 		this.entries[key] = entry;
-		try {
-			this.save();
-		} catch {
-			this.healthy = false;
-			return codec.resultOf({ kind: "reserve-failed" }, id);
-		}
+		if (!this.persist()) return codec.resultOf({ kind: "reserve-failed" }, id);
 		const run = (async () => {
 			let ran;
 			try {
@@ -4846,11 +4955,7 @@ var DispatchJournal = class {
 			} catch {
 				return codec.resultOf({ kind: "crashed" }, id);
 			}
-			try {
-				this.save();
-			} catch {
-				this.healthy = false;
-			}
+			this.persist();
 			return codec.resultOf({
 				kind: "ran",
 				entry,
@@ -5163,6 +5268,7 @@ let BRIDGE_SEQ = 0;
 var HostBridge = class {
 	apiProxy;
 	historyBufferMax;
+	log;
 	id = ++BRIDGE_SEQ;
 	summaries = /* @__PURE__ */ new Map();
 	activeTools = /* @__PURE__ */ new Map();
@@ -5183,26 +5289,30 @@ var HostBridge = class {
 	promptDeliveries;
 	scheduleMutations;
 	forkMutations;
-	constructor(apiProxy, historyBufferMax = MAX_RING_DEFAULT, deliveryJournalPath, scheduleJournalPath, forkJournalPath) {
+	constructor(apiProxy, historyBufferMax = MAX_RING_DEFAULT, deliveryJournalPath, scheduleJournalPath, forkJournalPath, log) {
 		this.apiProxy = apiProxy;
 		this.historyBufferMax = historyBufferMax;
+		this.log = log;
 		this.promptDeliveries = openDispatchJournal({
 			path: deliveryJournalPath,
 			codec: promptDeliveryCodec,
 			joinInFlight: true,
-			maxFileBytes: 8388608
+			maxFileBytes: 8388608,
+			log: this.log
 		});
 		this.scheduleMutations = openDispatchJournal({
 			path: scheduleJournalPath,
 			codec: scheduleMutationCodec(false),
 			joinInFlight: false,
-			maxFileBytes: 4194304
+			maxFileBytes: 4194304,
+			log: this.log
 		});
 		this.forkMutations = openDispatchJournal({
 			path: forkJournalPath,
 			codec: scheduleMutationCodec(true),
 			joinInFlight: false,
-			maxFileBytes: 4194304
+			maxFileBytes: 4194304,
+			log: this.log
 		});
 	}
 	pushOutlet;
@@ -7841,16 +7951,49 @@ function applyReportRemote(ctx, snapshot, pairingStarter, deviceRevoker, deviceR
 }
 //#endregion
 //#region src/local-address.ts
-function isPrivateIPv4(address) {
+function octetsOf(address) {
 	const octets = address.split(".").map(Number);
-	if (octets.length !== 4 || octets.some((value) => !Number.isInteger(value) || value < 0 || value > 255)) return false;
-	const [a, b] = octets;
+	if (octets.length !== 4 || octets.some((value) => !Number.isInteger(value) || value < 0 || value > 255)) return null;
+	return octets;
+}
+/** RFC1918 私有地址。名字保持诚实：它**不**包含 CGNAT 段，见 isSharedAddressSpaceIPv4。 */
+function isPrivateIPv4(address) {
+	const parsed = octetsOf(address);
+	if (parsed === null) return false;
+	const [a, b] = parsed;
 	return a === 10 || a === 172 && b >= 16 && b <= 31 || a === 192 && b === 168;
 }
+/**
+* RFC 6598 共享地址空间（100.64.0.0/10）。
+*
+* Tailscale 与 Headscale 都从这个段里给节点分配地址（Headscale 的
+* `prefixes.v4` 默认就是它），因此它在实践中是私有的，只是不是 RFC1918——
+* 这正是 `isPrivateIPv4` 会把它拒掉的原因。把它单列成一个谓词而不是塞进
+* `isPrivateIPv4`，是为了不谎报那个名字（issue #24）。
+*/
+function isSharedAddressSpaceIPv4(address) {
+	const parsed = octetsOf(address);
+	if (parsed === null) return false;
+	const [a, b] = parsed;
+	return a === 100 && b >= 64 && b <= 127;
+}
+/**
+* 可以交给手机的私有地址候选：RFC1918 加 CGNAT 段。
+*
+* 候选多于一个时，配对二维码页才会渲染地址选择器——只有一个候选时用户没有
+* 任何办法指定别的地址。把 tailnet 地址放进来，选择器才会出现，物理局域网
+* 离开之后用户仍可切到 tailnet 那个。
+*
+* 排序**不动**：物理 en* 接口仍然排在隧道接口之前，默认拿到的还是局域网地址，
+* 改变的只是「多了一个可选项」这件事本身。
+*/
+function isRoutablePrivateIPv4(address) {
+	return isPrivateIPv4(address) || isSharedAddressSpaceIPv4(address);
+}
 /** Private IPv4 candidates, preferring physical en* interfaces over tunnels. */
 function localLANIPv4Addresses() {
 	const candidates = [];
-	for (const [name, entries] of Object.entries(networkInterfaces())) for (const entry of entries ?? []) if (entry.family === "IPv4" && !entry.internal && isPrivateIPv4(entry.address)) candidates.push({
+	for (const [name, entries] of Object.entries(networkInterfaces())) for (const entry of entries ?? []) if (entry.family === "IPv4" && !entry.internal && isRoutablePrivateIPv4(entry.address)) candidates.push({
 		name,
 		address: entry.address
 	});
@@ -8785,7 +8928,7 @@ function apply(ctx, options) {
 			log("DSH session bridge unavailable: " + String(error));
 			return;
 		}
-		const bridge = new HostBridge(proxy, cfg.historyBufferMax, join(dataDir, "prompt-deliveries-v1.json"), join(dataDir, "schedule-mutations-v1.json"), join(dataDir, "fork-mutations-v1.json"));
+		const bridge = new HostBridge(proxy, cfg.historyBufferMax, join(dataDir, "prompt-deliveries-v1.json"), join(dataDir, "schedule-mutations-v1.json"), join(dataDir, "fork-mutations-v1.json"), log);
 		bridge.setPushOutlet(pushGateway);
 		state.bridge = bridge;
 		bridge.start();