@twinsearth/w2m-dsh-plugin 1.2.6 → 1.3.0

package/.claude-plugin/marketplace.json

@@ -1,29 +1,30 @@
-{
-    "name":  "twinsearth-w2m",
-    "owner":  {
-                  "name":  "TwinsEarth"
-              },
-    "metadata":  {
-                     "description":  "The w2m fleet plugins: one account, many machines, any of Windows, macOS or Linux.",
-                     "version":  "1.2.6"
-                 },
-    "plugins":  [
-                    {
-                        "name":  "w2m-fleet",
-                        "source":  "./",
-                        "description":  "Read fleet state and dispatch commands across the machines registered to one account. Read-only MCP surface: the five exposed tools cannot change anything.",
-                        "version":  "1.2.6",
-                        "author":  {
-                                       "name":  "TwinsEarth"
-                                   },
-                        "homepage":  "https://github.com/TwinsEarth/dsh-windows2macos",
-                        "repository":  "https://github.com/TwinsEarth/dsh-windows2macos",
-                        "license":  "MIT",
-                        "keywords":  [
-                                         "fleet",
-                                         "remote-execution",
-                                         "mcp"
-                                     ]
-                    }
-                ]
-}
+{
+  "name": "twinsearth-w2m",
+  "owner": {
+    "name": "TwinsEarth"
+  },
+  "metadata": {
+    "description": "The w2m fleet plugins: one account, many machines, any of Windows, macOS or Linux.",
+    "version": "1.3.0"
+  },
+  "plugins": [
+    {
+      "name": "w2m-fleet",
+      "source": "./",
+      "description": "Read fleet state and dispatch commands across the machines registered to one account. Read-only MCP surface: the five exposed tools cannot change anything.",
+      "version": "1.3.0",
+      "author": {
+        "name": "TwinsEarth"
+      },
+      "homepage": "https://github.com/TwinsEarth/dsh-windows2macos",
+      "repository": "https://github.com/TwinsEarth/dsh-windows2macos",
+      "license": "MIT",
+      "keywords": [
+        "fleet",
+        "remote-execution",
+        "mcp"
+      ]
+    }
+  ],
+  "version": "1.3.0"
+}

package/.claude-plugin/plugin.json

@@ -1,29 +1,29 @@
-{
-    "name":  "w2m-fleet",
-    "description":  "Drive the same project on online Windows, macOS and Linux machines from one account: read fleet state, dispatch commands and read results. The MCP surface is deliberately read-only.",
-    "version":  "1.2.6",
-    "author":  {
-                   "name":  "TwinsEarth"
-               },
-    "homepage":  "https://github.com/TwinsEarth/dsh-windows2macos",
-    "repository":  "https://github.com/TwinsEarth/dsh-windows2macos",
-    "license":  "MIT",
-    "keywords":  [
-                     "fleet",
-                     "remote-execution",
-                     "windows",
-                     "macos",
-                     "linux",
-                     "mcp",
-                     "claude-code",
-                     "codex"
-                 ],
-    "mcpServers":  {
-                       "w2m-fleet":  {
-                                         "command":  "node",
-                                         "args":  [
-                                                      "${CLAUDE_PLUGIN_ROOT}/bin/w2m-mcp.mjs"
-                                                  ]
-                                     }
-                   }
-}
+{
+  "name": "w2m-fleet",
+  "description": "Drive the same project on online Windows, macOS and Linux machines from one account: read fleet state, dispatch commands and read results. The MCP surface is deliberately read-only.",
+  "version": "1.3.0",
+  "author": {
+    "name": "TwinsEarth"
+  },
+  "homepage": "https://github.com/TwinsEarth/dsh-windows2macos",
+  "repository": "https://github.com/TwinsEarth/dsh-windows2macos",
+  "license": "MIT",
+  "keywords": [
+    "fleet",
+    "remote-execution",
+    "windows",
+    "macos",
+    "linux",
+    "mcp",
+    "claude-code",
+    "codex"
+  ],
+  "mcpServers": {
+    "w2m-fleet": {
+      "command": "node",
+      "args": [
+        "${CLAUDE_PLUGIN_ROOT}/bin/w2m-mcp.mjs"
+      ]
+    }
+  }
+}

package/CHANGELOG.md

@@ -7,6 +7,203 @@
 
 All notable changes to this project are documented here.
 
+## [1.3.0] — 2026-10-21
+
+The first stable release of the collaboration line. It consolidates the four betas that followed 1.2.7 and changes no protocol in a
+way that a 1.2.7 peer cannot ignore; every addition is additive and named.
+
+### Data plane
+
+**A reduce phase you can actually run.** `w2m_reduce` dispatches a reduce task only from complete data: it refuses unless every
+declared shard reported as a blob and the named reducer reported (`W2M_REDUCE_NOT_READY` with the missing indexes), never picks a
+reducer, and refuses inline inputs that cannot be carried to another machine. The relay validates, stores, ledgers and offers
+`reduce_of` + `reduce_inputs`; the agent fetches those content-addressed blobs before the reduce runs and exposes
+`W2M_REDUCE_INPUTS_DIR` / `W2M_REDUCE_MANIFEST` / `W2M_REDUCE_OF`; a failed fetch refuses the whole task rather than reducing a
+partial fleet.
+
+**A suggestion that dispenses no action.** `w2m_wait` carries `reduce_suggestion`: ready only when every declared shard reported and
+a reducer was named, the missing indexes otherwise, the candidate machines, and the literal next step. It is derived, never stored,
+and it dispatches nothing.
+
+**Message ids survive a restart, artifacts are one size everywhere.** Chat ids carry a random per-process relay epoch
+(`msg-<epoch>-<seq>`) so a restart cannot recycle an id a client persisted; the blob transport frame is 16 MiB, matching the agent's
+dataflow hard cap, instead of 1 MiB against it.
+
+### Collaboration
+
+**The panel shows the scheduler's own buckets.** The fleet-chat panel renders 准备 / 进行 / 等待 / 阻塞 counts beside the relay's task
+list, derived from the relay's `status` and `waiting_on`; read-only, no dispatch.
+
+**Conflicts name their next step.** `w2m_memory append` returns `merge_hint` with a 409: `re-read-then-append`, `behind_by`, the
+unseen count, the sample size and the literal instruction to re-read, compare and append against the current revision -- never an
+automatic merge.
+
+**Decisions leave a trail.** `w2m_council fleet-decide` reports `trail` (`appended` / `refused` / `error` / `not-written`), and the
+test asserts that status instead of implying a record exists.
+
+### Verified
+
+Gate GREEN twice, 15 of 15: 2710 tests / 2696 pass / 0 fail / 14 skip in 133 files. Two-machine live runs over the real relay cover
+the turn state machine (ask/await over SSE with a refusal), dependency scheduling, and the missing-shard refusal, plus the panel and
+proxy behaviour above.
+
+### Known limits, stated
+
+- `pipeline` keeps `index_total` at 1; blob map results come from plain commands above the inline cap.
+- The reduce suggestion is advisory: the caller dispatches the reduce (this release does not let the relay decide to run a command).
+- The composer panel does not render the board buckets on a host without the Connection service; the tools still work.
+
+## [1.2.11-beta.1] — 2026-10-21
+
+A beta by policy: GitHub prerelease only, never npm.
+
+### The task board in the composer panel
+
+The fleet-chat panel already listed the relay's tasks; it now also shows the four buckets the scheduler uses — 准备 / 进行 / 等待 / 阻塞 — derived from the relay's own `status` and `waiting_on`, never from a classification of its own. Read-only: the panel dispatches nothing.
+
+### Merge hint on memory conflicts
+
+`w2m_memory append` returns `merge_hint` with a 409: state `re-read-then-append`, `behind_by`, the number of unseen records, the sample size, and the literal next step (re-read, compare, append against the current revision — do not merge unseen records). Pure function, no automatic merge.
+
+### Council decisions leave a trail
+
+`w2m_council fleet-decide` reports `trail` (`appended` / `refused` / `error` / `not-written`) instead of implying a record exists; the test now asserts that status.
+
+Verified: gate GREEN twice, 2704 tests / 2690 pass / 0 fail / 14 skip in 132 files; client-bundle 25/25 after the board line; the merge-hint and trail tests are new.
+
+## [1.2.10-beta.1] — 2026-10-21
+
+A beta by policy: GitHub prerelease only, never npm. This one makes the reduce phase executable.
+
+### Reduce execution (caller-dispatched)
+
+`w2m_reduce` dispatches a reduce only from complete data: it refuses unless every declared shard reported as a blob and the named reducer reported (`W2M_REDUCE_NOT_READY`, with the missing indexes). It never picks a reducer and never invents inputs; inline results are refused (`W2M_REDUCE_INLINE_INPUT`) because they cannot be carried to another machine.
+
+The relay validates and carries `reduce_of` + `reduce_inputs` (at most 16 artifacts, sha256 only) on the task, the ledger and the offer; the agent fetches those content-addressed blobs BEFORE running the reduce and exposes `W2M_REDUCE_INPUTS_DIR` / `W2M_REDUCE_MANIFEST` / `W2M_REDUCE_OF` to the command. A failed fetch refuses the task (`REDUCE_INPUT_FETCH_FAILED`) rather than reducing half the fleet.
+
+Verified: gate GREEN twice, 2701 tests / 2687 pass / 0 fail / 14 skip in 131 files; new agent e2e proves the reduce reads the exact artifact bytes; the tool has a dispatch test and a refusal test.
+
+## [1.2.9-beta.1] — 2026-10-21
+
+A beta by policy: **GitHub prerelease only, never npm.** The theme is the data plane and the collaboration plane: the design is
+written down (`docs/DATA-PLANE-COLLABORATION.md`) and this release ships its first slice.
+
+### `reduce_suggestion` on `w2m_wait`
+
+Every terminal wait now answers three questions without acting on them: is the data complete, who could reduce it, and what the
+caller is supposed to do next (`dispatch the reduce yourself; this tool does not run it`). It is a pure function over the machine
+facts the aggregate already publishes:
+
+- **ready** only when every declared shard reported and a reducer was named;
+- **missing indexes** when a shard never reported (an expired lease cannot claim one);
+- **candidates** listing the machines that reported, with the reason;
+- a named reducer that never reported is refused by name (`REDUCER_UNREPORTED`) rather than silently replaced -- changing the
+  machine changes what the reduce runs against;
+- a caller that named no reducer gets `REDUCER_MISSING` and candidates, never an invented choice.
+
+Nothing is stored and nothing is dispatched. Two readers of the same aggregate get the same suggestion, and reading does not
+change relay state.
+
+### The design document states the open question
+
+Caller-dispatched reduce (current direction) versus auto-reduce in the relay. The design leans caller-dispatched, because a relay
+that decides to run a command is the boundary every other decision avoids; a beta that flipped that default would be the wrong
+place to discover it. The document also names the next collaboration slices: conflict-merge UI, council decision trail to shared
+memory, and the board in the composer panel.
+
+### Verified
+
+Gate GREEN twice: 2699 tests / 2685 pass / 0 fail / 14 skip in 131 files. New: `suggestReduce` unit tests (7) covering complete,
+partial-with-missing, no-reducer, unreported-reducer and mixed inline+blob inputs; `w2m_wait` carries the suggestion for every
+aggregate.
+## [1.2.8-beta.1] — 2026-10-21
+
+A beta, by policy: **not published to npm**. It is a GitHub prerelease, installable by a developer who asks for it.
+
+### Message ids are unique across a relay restart
+
+The relay's chat sequence resets on restart, so a bare `msg-000001` named a different message after every deploy. Clients persist
+those ids -- an open turn, a read watermark, `reply_to` -- and live testing caught exactly that: a Windows `ask` recorded a turn, the
+relay restarted, a new message reused the id, and the wait settled the OLD turn as `answered_after_timeout` while the reply was
+fresh. Message ids now carry a random per-process epoch (`msg-<epoch>-<seq>`), so a restart cannot recycle an id and old clients that
+render ids verbatim keep working.
+
+### One size for "how large may one artifact be"
+
+The blob transport frame was 1 MiB while the agent's dataflow hard cap is 16 MiB, so an artifact between the two was accepted by the
+agent and then failed its upload (`BLOB_UPLOAD_FAILED`) on a relay that looked fine. `BLOB_FRAME_BYTES` is now 16 MiB, matching the
+agent, while every JSON route keeps the 64 KiB frame limit.
+
+### Verified
+
+Gate GREEN twice: 2691 tests / 2677 pass / 0 fail / 14 skip in 130 files. New tests: an id is unique across two store instances
+(same sequence, different process), an explicit epoch is honoured, and a 2 MiB blob survives the transport intact.
+
+### Still open (unchanged from 1.2.7)
+
+- `pipeline` keeps `index_total` at 1; blob map results come from plain commands above the inline cap.
+- macmini runs 1.2.6 from its own checkout and needs a `git pull` + restart for the plain-command blob behaviour.
+## [1.2.7] — 2026-10-21
+
+**The scheduler enforces the graph, a wait survives a restart and a dropped stream, and a partial fleet can no longer call itself
+a complete reduce.**
+
+### Turns are a state machine on disk
+
+A question written with `action:'ask'` becomes a persisted turn (`ask_id`, deadline). `await` attaches to that record, so a process
+restart does not lose the question or turn a late answer into silence; a late answer is recorded as `answered_after_timeout`. The
+wait prefers the relay's event stream, re-subscribes when the stream drops, and polls only when streaming is unavailable. A reply
+now carries `reply_state: 'answered'|'refused'`, so a refusal is a state the waiter reads rather than wording it guesses.
+
+### Dependencies block dispatch, and release when their prerequisite settles
+
+A task with `depends_on` is not offered: its leases are `waiting`, which redelivery skips and the sweeper ignores. When every
+prerequisite is settled -- **by a result, an expiry or a refusal** -- `_releaseDependents` moves those leases to offers. The graph
+edges and `assignee` are written into the task ledger, because live testing showed a restarted relay losing them and keeping a
+waiting task waiting forever. `assignee` is enforced, not recorded: only that machine gets a lease, and an unknown assignee is
+refused by name. `GET /v1/tasks` now publishes a derived `status` (`waiting`/`active`/`done`/`failed`/`cancelled`) and
+`waiting_on`, so the board and the scheduler cannot disagree.
+
+### Dataflow: an expected shard count, and a reduce that refuses partial input
+
+`buildReducePlan` takes `expectedIndexTotal` from the task (`index_total`) and refuses `MISSING_SHARD` (with the missing indexes),
+`MAP_INDEX_MISSING` and `MAP_INDEX_OUT_OF_RANGE`; only machines that actually reported can claim a shard, so an expired lease no
+longer makes a partial run look complete. Two production gaps were found by live testing and closed with it:
+
+- **A large plain-command stdout was never a blob.** The blob path lived only in the pipeline loop, so a split/mapreduce map result
+  was always inline and a reduce plan could never see what it reduces. Any command output above the inline cap now uploads a blob
+  exactly as a pipeline stage does (best effort: a failed upload keeps the command successful and says why).
+- **The relay's own frame limit made the blob channel unusable.** `MAX_FRAME_BYTES` (64 KiB) equals the inline threshold, so every
+  blob was by construction larger than the frame cap and a real upload failed with `FRAME_TOO_LARGE` while the fake relay in tests
+  accepted it. Blob PUTs now get a bounded 1 MiB frame (`BLOB_FRAME_BYTES`); every JSON route keeps the 64 KiB cap.
+- The aggregate now publishes `blob_sha256`, `output_mode`, `stdout_head` and `stdout_bytes` per machine: `w2m_wait` used to read
+  `aggregate.detail.machines`, a shape the production `/v1/tasks` response never carries, so the reduce plan was unreachable
+  outside tests.
+
+### Verified
+
+Gate GREEN twice, 15 of 15: 2687 tests / 2673 pass / 0 fail / 14 skip in 130 files.
+
+Two-machine live runs on Windows (ToFuture) and jp-shared over the real relay:
+
+- **await over SSE**: Windows asks, jp-shared replies `reply_state:'refused'`; the wait returns `state=refused, via=stream`, and the
+  turn is settled on disk.
+- **dependency chain**: B with `depends_on: [A]` is `waiting`, A settles, B is released (observed `status=active` with offers).
+- **missing shard**: a split task with `index_total: 5` whose map results are blobs is refused as
+  `MISSING_SHARD {missing:[1,3,4], expectedIndexTotal:5}` with `dataflow_degraded: true` -- the first live exercise of the blob
+  channel end to end.
+
+Both live-testing defects above (release only on a result; graph edges missing from the ledger) were found by these runs and are
+covered by tests now.
+
+### Limits, stated
+
+- A pipeline task runs the whole chain per machine, so `index_total` stays 1 for it; blob map results come from plain commands above
+  the inline cap.
+- The blob transport frame is 1 MiB while the agent's dataflow hard cap is 16 MiB: a single artifact above 1 MiB fails its upload
+  explicitly (`BLOB_UPLOAD_FAILED`) rather than being split across frames.
+- The jp-shared agent was upgraded to this build; macmini runs 1.2.6 from its own checkout and needs a `git pull` + restart to get
+  the plain-command blob behaviour.
 ## [1.2.6] — 2026-10-20
 
 **Security surface: signatures, a permission matrix, and output that no longer carries secrets — plus the reliability the chat

package/README.md

@@ -14,7 +14,7 @@ English | [中文](#中文说明)
 
 ## Install
 
-Five routes in. They all end with **15 tools registered** in your agent. Pick one.
+Five routes in. They all end with **16 tools registered** in your agent. Pick one.
 
 ### 1. DSH plugin (recommended — zero configuration)
 
@@ -136,7 +136,7 @@ hand-maintained host list.
 ### Tools
 
 `w2m_status` · `w2m_devices` · `w2m_run` · `w2m_wait` · `w2m_history` · `w2m_stats` · `w2m_report` ·
-`w2m_memory` · `w2m_approvals` · `w2m_cancel` · `w2m_council` · `w2m_chat` · `w2m_update` `w2m_tasks`
+`w2m_memory` · `w2m_approvals` · `w2m_cancel` · `w2m_council` · `w2m_chat` · `w2m_update` `w2m_tasks` · `w2m_reduce`
 - `w2m_intent` — map a structured intent (run-tests, node-version, git-status, git-head, fleet-facts, shard-probe) onto an allow-listed command; unknown intents are refused by name, never guessed.
 
 ### Environment a dispatched command receives (1.1.15+)
@@ -261,7 +261,7 @@ MIT.
 
 ### 安装
 
-五种方式，最终都会在你的 agent 里注册 **15 tools registered**。任选其一。
+五种方式，最终都会在你的 agent 里注册 **16 tools registered**。任选其一。
 
 #### 1. DSH 插件（推荐，零配置）
 

package/codex/mcp-servers.toml

@@ -12,6 +12,6 @@
 
 [mcp_servers.w2m-fleet]
 command = "npx"
-args = ["-y", "-p", "@twinsearth/w2m-dsh-plugin@1.2.6", "w2m-mcp"]
+args = ["-y", "-p", "@twinsearth/w2m-dsh-plugin@1.3.0", "w2m-mcp"]
 startup_timeout_sec = 20
 tool_timeout_sec = 60

package/docs/DATA-PLANE-COLLABORATION.md

@@ -0,0 +1,82 @@
+# Data plane and collaboration: the design this fleet is building toward
+
+> Status: **design + first slice (v1.2.9-beta.1)**. The slice is a pure function that turns an aggregate into a *reduce
+> suggestion*; it dispatches nothing. Everything below the slice is the plan the slice is measured against, not a claim that it
+> exists.
+
+## 1. What "data plane" means here
+
+A task has three planes in this fleet:
+
+| plane | what moves | owns |
+|---|---|---|
+| control | dispatch, leases, retries, cancellation | relay (`state.mjs`) |
+| data | command output, stage artifacts, blobs | agent (`agent.mjs`) + relay blob store |
+| collaboration | chat, turns, memory, council | plugin (`tools.mjs`, `ask-store.mjs`, `council-fleet.mjs`) |
+
+The data plane is **not allowed to make a verdict**. It moves bytes; the aggregate decides. That rule is why the reduce plan is
+computed by a reader (`w2m_wait`) from published facts, and why this release adds only a *suggestion*: a party that has the plan
+must still be the one that says "run the reduce".
+
+## 2. The shard contract (implemented in v1.2.7)
+
+1. A task declares `index_total`. It is the completeness contract, not a hint.
+2. A result claims a shard with `index`; only machines that actually reported count.
+3. `buildReducePlan({ results, reducerMachineId, expectedIndexTotal })` refuses:
+   - `MISSING_SHARD` + `{ missing, expectedIndexTotal }`,
+   - `MAP_INDEX_MISSING`, `MAP_INDEX_OUT_OF_RANGE`,
+   - `BLOB_MISSING`, `MAP_MACHINE_MISSING`, `NO_MAP_RESULTS`.
+4. An artifact above the inline cap is a blob (`blob_sha256` + `output_mode: 'blob'`), uploaded by the agent, addressed by its own
+   hash, transport frame 16 MiB.
+5. **A partial fleet never reduces.** `dataflow_degraded: true` is the value; a caller that ignores it is ignoring a stated fact.
+
+## 3. What v1.2.9-beta.1 adds: `suggestReduce`
+
+`w2m_wait` now returns a `reduce_suggestion` alongside the verdict:
+
+```json
+{
+  "ready": true,
+  "plan": { "ok": true, "reducerMachineId": "…", "inputs": [ … ] },
+  "candidates": [{ "machine_id": "…", "reason": "reported-shard" }],
+  "next": "dispatch the reduce yourself; this tool does not run it"
+}
+```
+
+Rules it encodes:
+
+- **Ready means all declared shards reported and a reducer is named.** Anything else is a value with the missing indexes.
+- **The reducer is not chosen by the tool.** It lists candidates (machines that reported, preferring the declared
+  `reducer_machine_id` when present) and refuses to invent one: a reduce that runs on an arbitrary machine is a second dispatch
+  decision, and dispatch belongs to the caller.
+- **The suggestion is derived, never stored.** Two readers of the same aggregate get the same suggestion, and no relay state
+  changes by reading it.
+
+## 4. The reduce execution question (open)
+
+Two shapes are possible, and the fleet has not chosen one:
+
+| shape | dispatch of reduce | trade |
+|---|---|---|
+| **caller-dispatched** (current direction) | the caller reads the plan and dispatches a task with `reduce_argv` to the named reducer | relay never decides to run a command; one extra round trip and the caller can ignore the plan |
+| **auto-reduce** | the relay, on all-shards-reported, dispatches the reduce itself | fewer steps; the relay becomes an executor of a command it chose, which is the boundary every other design decision avoids |
+
+The design leans caller-dispatched. A beta that flips that default would be the wrong place to discover it.
+
+## 5. Collaboration plane, next
+
+The collaboration gaps that remain after v1.2.6/v1.2.7 (turns, DAG, membership, memory CAS) are:
+
+1. **Conflict merge UI** — `w2m_memory read` returns `behind_by`/`unread_records`; a reader can see a conflict but has no guided
+   merge. Next slice: a pure `renderMergeHint()` and a re-read flow that shows both sides of a conflicting record.
+2. **Council decision trail** — `council-fleet.mjs` decides and reports; the decision is not written to shared memory. Next slice:
+   an explicit, caller-invoked append of the decision as a memory record (same CAS as any other write).
+3. **DAG visibility in the client** — the board exists in `w2m_tasks`; the composer panel does not show it. Next slice: a read-only
+   board view from the same endpoint.
+
+## 6. Acceptance for this design
+
+- The suggestion is a pure function with unit tests for: all shards present, missing shards, no reducer named, mixed
+  inline+blob inputs, and a duplicate machine index.
+- `w2m_wait` carries it for every complete aggregate and never dispatches anything.
+- Gate GREEN twice before the beta tag; beta artifacts are a GitHub prerelease, never npm.