@twinsearth/w2m-dsh-plugin 0.46.0 → 0.48.0

package/CHANGELOG.md

@@ -4,6 +4,96 @@ All notable changes to this project are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.48.0] — 2026-10-15
+
+**`--dry-run` dispatched. Two dry runs sent a command to five machines, and one made a real task.**
+
+### The defect, measured before it was described
+
+The bridge guarded exactly one thing under `--dry-run`: the **reply**. The dispatch ran unconditionally.
+
+```
+[15:13:57] dry run     : true
+[15:15:00]   dispatched task 01M50231AYJYDD41WSPMS9PRM3
+[15:15:50]   verdict for …: partial
+```
+
+**That is a real task record with five real leases, produced by a run whose flag promised nothing would
+happen.** A rehearsal executed commands on production machines — and it was found by accident, while draining
+a message queue, not by a test.
+
+### Why the fix is "skip the dispatch" and not "rename the flag"
+
+**This repository already fixes the meaning of the word.** `update-install`'s `dryRun` is asserted to **call no
+package manager and write nothing**, and `auto-update`'s is asserted to **write nothing to the profile**. So a
+second `dry-run` meaning "do the dangerous part anyway" is not a naming preference — **it is two flags with one
+name and opposite meanings, and the bridge held the unsafe one.**
+
+**Renaming would have left the flag. Aligning keeps the word and removes the hazard**, and a reader who knows
+`dryRun` from anywhere else in this project is now already right about this one.
+
+### Why the guard is a function in `lib`, not an `if` in the script
+
+`scripts/` is **not in `package.json#files`**, so nothing there is covered by a test that ships. A safety
+property expressed as one line inside an untested script is a property nobody re-checks. `dryRunPolicy` is
+exported and asserted beside the wire shapes — **a script is not where a guard should live if the guard is the
+point.**
+
+The guard sits at the **top of the only function that reaches `fleet.run`**, not at its call site, because a
+guard at the call site is one edit away from being bypassed by a second caller.
+
+### A name collision that made my own test wrong
+
+I asserted that `dryRun: 'true'` must not dispatch. **It does dispatch — the code was right and the test was
+wrong**, and the cause is two different things sharing one word:
+
+| | meaning |
+|---|---|
+| the CLI **flag** `--dry-run` | **present-means-true** (`argv.includes('--dry-run')`) |
+| the **parameter** `dryRun` | **defaults to false**, which is what `update-install` means by it |
+
+`dryRunPolicy` takes the parameter, and the script always hands it a boolean. The assertion is now the strict
+one — **only `true` turns the dispatch off, so a future caller cannot open the path with a truthy value.**
+
+**5 new tests, 0 failures.** One of them reads the script and asserts the guard appears **before** the only
+call that can reach the fleet — because a test of the pure function alone would pass while the script still
+dispatched, **which is precisely the shape of the original defect.**
+
+## [0.47.0] — 2026-10-15
+
+**Correcting my own counts: 0.46.0 said 54/32/22, the table says 61/53/8.**
+
+0.46.0's entry claimed *"**54 rows** across twelve sections"*, *"**32 of 54** rows are executed; **22** are not"*.
+**All three numbers were typed by hand, and all three were wrong.** Read from `docs/TEST-MATRIX.md`:
+
+| | 0.46.0 said | the table says |
+|---|---|---|
+| rows | 54 | **61** |
+| executed | 32 | **53** |
+| not executed | 22 | **8 never run**, plus **11 blocked**, **1 skipped**, **2 refuted** |
+
+### The cause is that I merged two words that are not the same
+
+**`阻塞` means the command RAN and the environment stopped it. `待执行` means it never ran at all.** I collapsed
+both into "not executed" — **and a count that merges two categories is wrong in both directions at once**: it
+overstates what was never attempted and understates what was attempted and blocked.
+
+**The matrix now marks `阻塞` as "the command executed" explicitly, and carries a note recording this mistake**,
+because the distinction is the one a reader needs in order to tell "we have not tried" from "we tried and were
+stopped".
+
+### It is the same error the matrix itself documents, one level up
+
+The matrix's own rule is that **a row's result may only be changed by re-running its `Instance` and reading the
+output**, and that a count copied from an older plan becomes more true-looking each time it is copied. **I then
+wrote the headline counts of the document from memory instead of reading the document.** The rule was in the
+file I was writing.
+
+**So the counts are no longer asserted anywhere by hand.** They are read from the table, and the reading is
+recorded: `61 = 39 通过 + 8 待执行 + 11 阻塞 + 1 跳过 + 2 证伪`.
+
+**No new tests.** What changed is three numbers and the reason they drifted.
+
 ## [0.46.0] — 2026-10-15
 
 **The test matrix the plans asked for — with every row it could not earn left as `待执行`, and the reason named.**

package/docs/TEST-LEDGER.md

@@ -118,6 +118,7 @@ was not re-measured keeps its old date — **a stale date is information, and qu
 | `GATE-002` | an accepted orphan that is no longer an orphan fails — the list cannot go stale | **PASS** | 2026-10-15 | `field-authority` was removed when 0.41.0 gave it a caller, **because this check went red** |
 | `GATE-003` | `layer-check` prints `clean` **and exits 0** | **PASS** | 2026-10-15 | after the fix. **Before it printed `clean:` and exited `1`** — every reader trusting the status read a passing check as a failure; the pre-flight never noticed because its step reads the *printed text* |
 | `HARNESS-001` | a hand-rolled test harness measures the harness | **PASS (as a warning)** | 2026-10-15 | **41 failures** running every suite in one process with `--experimental-test-isolation=none`, vs **1** via the project's own entry. The other 38 were `mdns-discover`'s fetch stub leaking into `outbound-only` |
+| `HARNESS-002` | **a count typed by hand drifts from the table it describes** | **FAIL, then corrected** | 2026-10-15 | CHANGELOG 0.46.0 claimed *"54 rows / 32 executed / 22 not"*. Read from `TEST-MATRIX.md`: **61 rows / 53 executed / 8 never run / 11 blocked / 1 skipped / 2 refuted.** I had merged **`阻塞`** (the command ran and the environment stopped it) with **`待执行`** (never run) — so 61 became 54 and 8 became 22 |
 
 ---
 

package/docs/TEST-MATRIX.md

@@ -13,12 +13,16 @@
 |---|---|
 | **通过** | 已执行，且期望成立 |
 | **失败** | 已执行，且期望不成立 |
-| **阻塞** | 已执行，但被环境挡住（**并写明被什么挡住**） |
+| **阻塞** | **命令执行了**，结果被环境挡住（**并写明被什么挡住**） |
 | **跳过** | 平台不适用，套件自报原因 |
 | **待执行** | **未执行**。必须写明为什么，否则这一行只是噪声 |
 | **证伪** | 计划中的一条主张被测量推翻 |
 
 > **一行"通过"必须能追到一个 `Instance`。追不到的，写"待执行"。** 这一条比表里任何数字都重要——它是本表唯一不能违反的规则。
+>
+> **"阻塞"与"待执行"不是同一件事，而我把它们混为一谈过一次。** 阻塞 = 命令**执行了**，被环境挡住；待执行 = **从未运行**。
+> 在 CHANGELOG 0.46.0 里我手数成"54 行 / 22 未执行"，把两者合并了——**而从本表读出来是 61 行 / 8 待执行 / 11 阻塞**。
+> **手数的计数会漂移，所以本节的所有数字都是从表格里读出来的。**
 
 ---
 
@@ -159,9 +163,10 @@
 | 热修复 | 对应失败项 + 相邻模块回归 | 修复后必须回归通过 |
 | 季度/半年 | 全表重跑一次 | 防止环境漂移导致漏测 |
 
-### 这张表当前的"未执行"分布，以及它们是不是同一件事
+### 这张表当前未通过的分布，以及它们是不是同一件事
 
-**54 项里 32 项已执行，22 项未执行。** 未执行的**不是 22 个独立问题，而是 4 个阻塞源**：
+**61 项里 53 项已执行，8 项从未运行，11 项被执行但被环境挡住，1 项平台跳过。**
+未通过的**不是一堆独立问题，而是 4 个阻塞源**：
 
 | 阻塞源 | 卡住的项 | 解锁条件 |
 |---|---|---|
@@ -170,7 +175,7 @@
 | **没有可用配对码** | `TC-PAIR-003/004/005` | 一次可控的配对实验；会惊动编队，需你同意 |
 | **需要真实中断或外部资源** | `TC-UPD-001/002/004/005/007` | 一次真实更新检查；`TC-SEC-007` 需要 macOS/Linux |
 
-> **22 项未执行 ≠ 22 项风险。** 它们集中在 4 处，其中**两处**（中继升级、唤醒 Windows 机器）是可以立刻解决的。
+> **未通过的项 ≠ 未通过的项数那么多风险。** 它们集中在 4 处，其中**两处**（中继升级、唤醒 Windows 机器）是可以立刻解决的。
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twinsearth/w2m-dsh-plugin",
-  "version": "0.46.0",
+  "version": "0.48.0",
   "description": "DSH: Windows2MacOS — drive the same project on online Windows and macOS machines from one DeepSeek account, across networks and regions. P2P hole punching is the default path (relay + shared server as rendezvous, ledger and fallback), with a bundled STUN responder, Tailscale/public-VPS/tunnel shapes, Rabbit relay + per-machine Localside + eight DSH tools (replicate / split), nine aggregate verdicts and signed requests.",
   "type": "module",
   "main": "lib/index.js",

package/src/chatops/ilink-fleet-bridge.mjs

@@ -25,6 +25,47 @@
 
 import { parseInvocation, renderVerdict, renderDispatchFailure } from './run-command.mjs';
 
+/**
+ * What a run with `--dry-run` set is allowed to do.
+ *
+ * ## The defect this exists to make unreachable
+ *
+ * `scripts/ilink-fleet-bridge.mjs` guarded exactly one thing under `--dry-run`: the **reply**. The
+ * dispatch itself ran unconditionally, so **two dry runs sent `node--version` to all five machines**
+ * — and one of them produced a real task record with five real leases. The flag's name promises that
+ * nothing happens, and the promise was false in the direction that matters: **a rehearsal executed
+ * commands on production machines.**
+ *
+ * ## Why "skip the dispatch" rather than "rename the flag"
+ *
+ * This repository already fixes the meaning of the word. `update-install`'s `dryRun` is asserted to
+ * **write nothing and call no package manager**, and `auto-update`'s is asserted to **write nothing to
+ * the profile**. So a second `dry-run` that means "do the dangerous part anyway" is not a naming
+ * preference — it is two flags with one name and opposite meanings, and the bridge held the unsafe one.
+ *
+ * **Renaming would have left the flag. Aligning keeps the word and removes the hazard**, and it means
+ * a reader who knows `dryRun` from anywhere else in this project is already right about this one.
+ *
+ * ## Why this is a function rather than an `if` in the script
+ *
+ * `scripts/` is not in `package.json#files`, so nothing there is covered by a test that ships. A safety
+ * property expressed as one line inside an untested script is a property nobody re-checks. As an
+ * exported function with a name, it is asserted in `chatops-ilink-fleet-bridge.test.mjs` beside the
+ * wire shapes — **a script is not where a guard should live if the guard is the point.**
+ *
+ * @param {{ dryRun?: boolean }} [options]
+ * @returns {{ dispatch: boolean, reply: boolean, reason: string|null }}
+ */
+export function dryRunPolicy(options = {}) {
+  if (options.dryRun !== true) return { dispatch: true, reply: true, reason: null };
+  return {
+    dispatch: false,
+    reply: false,
+    // Carried so the caller logs *why* nothing happened rather than printing a bare "[dry-run]".
+    reason: 'dry run: the fleet was not dispatched to, and no reply was sent',
+  };
+}
+
 /** The header every authenticated call needs; undocumented and mandatory. */
 export const AUTH_TYPE = 'ilink_bot_token';
 export const APP_ID = 'bot';

package/src/plugin/tools.mjs

@@ -208,7 +208,7 @@ const MAX_STAGES = 16;
  * `package.json` during `scripts/pack.mjs` rather than hand-maintained, and `W2M_PLUGIN_VERSION`
  * overrides it at runtime for tests and packagers.
  */
-const PLUGIN_VERSION = '0.46.0';
+const PLUGIN_VERSION = '0.48.0';
 
 /** How long any single HTTP call may take before it is aborted, in milliseconds. */
 const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;