@twinsearth/w2m-dsh-plugin 0.10.4 → 0.10.5

package/CHANGELOG.md

@@ -4,6 +4,66 @@ 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.10.5] — 2026-10-15
+
+**FLEET-RULES.md enters the tree, with this host's reachability measured and written down.**
+
+### What was actually wrong
+
+The 1.0.0 objective starts with *"local Windows and MacMini jointly"*, and on inspection the Windows host
+had never been a git participant at all: its working copy was not a repository, and every release so far had
+been published through the GitHub REST API rather than through git. That is a real gap and it was recorded
+as one rather than glossed over.
+
+### Why it was that way, measured rather than assumed
+
+`github.com:443` is unreachable from this host while every other GitHub endpoint answers. Three consecutive
+`git fetch` attempts failed after ~21 s each, and from the same process minutes apart:
+
+| Endpoint | Result |
+|---|---|
+| `github.com:443` | **TIMEOUT** |
+| `api.github.com:443` | OPEN 73 ms |
+| `codeload.github.com:443` | OPEN 77 ms |
+| `ssh.github.com:443` | OPEN 95 ms |
+| `objects.githubusercontent.com:443` | OPEN 228 ms |
+
+The blocking is **per hostname, not per port** — `ssh.github.com` answers on the same 443 that `github.com`
+does not. It is also **intermittent at the TCP layer**: a raw `net.connect` to `20.205.243.166:443` timed out
+while a `tls.connect` to the same IP with `servername: 'github.com'` completed `authorized: true` on TLS 1.3.
+An intermittent block is worse than a solid one, because a single success is not evidence the path works.
+
+The first two attempts at this treated the failure as a configuration problem and tried proxy settings and
+retries. Both were wrong, and both cost a round. The measurements are cheaper to read than to repeat, which
+is why they are now rule 8 of `FLEET-RULES.md` rather than a note in a session log.
+
+### What now works, and what the evidence is
+
+The repository is materialised from a `codeload` tarball (the one path that is reachable), giving a real git
+work tree containing exactly `main` — verified by hashing both trees: **227 files, 0 differences,
+`IDENTICAL`**. `scripts/fleet-sync.mjs` then ran against a real repository for the first time, having only
+ever been tested against a temporary one:
+
+| Step | Result |
+|---|---|
+| initial | `state=up-to-date action=none` |
+| local commit | `state=ahead action=push ahead=1` |
+| `--write` | `performed: true - pushed 1 commit(s)`; mirror and HEAD agree |
+| peer commit arrives | `state=behind action=fast-forward behind=1` |
+| `--write` | `performed: true - now at d42d5c0`; 228 files, peer file present |
+| final | `state=up-to-date action=none` |
+
+The same run also demonstrated the refusal path for free: when a fast-forward was rejected by git, the
+result was `performed: false`, the tree was **left untouched**, and the state stayed `behind` — an automatic
+sync that fails must not half-apply.
+
+### Stated plainly rather than implied
+
+This host can *pull* the truth and can *run* the sync machinery, but it **cannot push over git**. A round
+that needs a commit published must use the API, and a round that exercises `fleet-sync` must do it against a
+local bare remote. That is a real test of the state machine and **not** a test of the network, and the
+difference is written into the rule so it is not mistaken for one.
+
 ## [0.10.4] — 2026-10-15
 
 **A result channel over exit codes, for machines whose text cannot be read back.**

package/FLEET-RULES.md

@@ -0,0 +1,146 @@
+# Fleet working rules
+
+Standing rules for every machine and every session in this fleet. These are **rules**, not notes: a
+session that finds itself working around one of these is either misreading it or should be proposing an
+amendment, not quietly making an exception.
+
+Established 2026-10-14/15. Amended by appending with a date and a reason — never by deleting, because
+*"we believed X until we measured Y"* is itself knowledge, and it is what stops the same wrong conclusion
+being reached twice.
+
+---
+
+## 1. Broadcast, sync, merge — automatically, in the same fleet
+
+**Added 2026-10-15 at the operator's instruction.**
+
+Any machine that is in the same fleet **broadcasts its state, syncs from the fleet, and merges without
+being asked**. This is not an optimisation; it is the rule that removes the class of work that produced
+2026-10-14's largest time sink — a session holding one copy of the truth on one machine while another
+machine held a different copy, and a human having to notice.
+
+### What the rule means concretely
+
+| Verb | Obligation |
+|---|---|
+| **Broadcast** | Before finishing a unit of work, publish what changed to the shared record — commit to the remote, not to a local branch nobody else can see. |
+| **Sync** | On starting a unit of work, fetch. A machine that has not fetched does not know what it is working on. |
+| **Merge** | Reconcile rather than choose. Two machines that both changed something must end with one tree, not with one machine's version silently winning. |
+
+### The shared record is the remote
+
+One repository, one remote, `main` as the integration point. Local-only work is not broadcast, and a
+branch that is not pushed is a branch no other machine can sync from — which is why a work-in-progress
+reaches another machine as a **pushed branch**, never as a file copied by hand.
+
+### What must never be merged
+
+- **A tree that has not passed its own tests.** Merge is not the place to discover a failing suite. The
+  rule is: run the suite where the change will land, and merge after it is green.
+- **Generated or machine-local state.** `dist/`, `node_modules/`, `memory.jsonl`, state directories and
+  credentials are per-machine facts; broadcasting them would spread one machine's local state over
+  another's. The repository already excludes these at the release boundary, and the same list applies
+  here.
+- **Anything a machine could not itself verify.** An unverified claim is broadcast as *unverified*, never
+  as a fact — see rule 4.
+
+### Why the rule is safe to apply automatically
+
+Git's fast-forward is the common case: one machine ahead, everyone else behind. A genuine divergence is
+the case that needs judgement, so the automation is: **fast-forward automatically, rebase automatically
+when the local work is not yet published, and stop and report when both sides have published** — because
+that is the only case where merging could discard someone's verified work.
+
+---
+
+## 2. Do not claim a mechanism works from a scheduling record
+
+Added 2026-10-14, after two mistakes in one session.
+
+A dispatch being accepted, a lease being granted, and a verdict arriving are three different
+observations. The reliable evidence is **a side effect on the target machine**, or **an exit code that
+nothing else would produce**. "The relay said `exit_code: 0`" is not evidence that a command ran until
+something else corroborates it.
+
+## 3. Run the suite where the change will land
+
+Added 2026-10-14. A green suite on the development host and a green suite on the target machine are
+different claims, and only the second one supports a merge. `scripts/` and `test/` are absent from the
+published tarball by design, so "it passes at home" cannot be checked from an installed copy.
+
+## 4. Mark what could not be verified
+
+Added 2026-10-14. If a check cannot run here — no network, no installation, no credential — it is reported
+as `UNVERIFIED` with the reason, never as a pass. An unverifiable check is not a passing check.
+
+## 5. Facts carry their date and how they were measured
+
+Added 2026-10-14, from `fleet-memory.md`.
+
+A fact without provenance is a rumour that outlives the person who could have checked it. Correct in
+place with a note rather than deleting: the correction is part of the record.
+
+## 6. Machine roles are not interchangeable
+
+Added 2026-10-14.
+
+| Machine | Role | Constraint |
+|---|---|---|
+| the Linux relay host | relay, STUN, archive, and the development shell over SSH | no personal data |
+| MacMini | real-machine work: deploy, run, test, verify, report, and now development | no personal data |
+| `ToFuture` (the DSH host) | orchestration | **hard-protected**: nothing outside the session workspace or non-system `C:` folders without the operator typing the password |
+| other Windows hosts | as MacMini | — |
+
+## 7. A note about the rule itself
+
+Rule 1 says merge automatically. That is a real transfer of authority from the human to the machines, and
+it is only defensible while the checks in rules 2, 3 and 4 hold: **automatic merging is safe exactly to
+the extent that "green" is trustworthy.** If a suite is ever found to pass without testing what it names
+— which happened twice on 2026-10-14, once in a cycle-detection test that asserted nothing — then this
+rule is the thing that spreads the damage. So a test that does not test is not a small defect here; it is
+a hole in the merge gate.
+
+---
+
+## 8. This host's reachability, measured — do not re-derive it
+
+**Added 2026-10-15 after round 3 of the 1.0.0 goal, because the same wrong assumption cost three rounds.**
+
+The Windows host that writes this file cannot reach `github.com:443`. Measured, not inferred: three
+consecutive `git fetch` attempts each failed after ~21 s with *"Failed to connect ... Could not connect to
+server"*, while the following, probed from the same process minutes apart, all succeeded:
+
+| Endpoint | Result |
+|---|---|
+| `github.com:443` | **TIMEOUT** |
+| `api.github.com:443` | OPEN 73 ms |
+| `codeload.github.com:443` | OPEN 77 ms |
+| `ssh.github.com:443` | OPEN 95 ms |
+| `objects.githubusercontent.com:443` | OPEN 228 ms |
+
+The blocking is **per hostname, not per port** — `ssh.github.com` answers on the same 443 that
+`github.com` does not. It is also **intermittent at the TCP layer**: a raw `net.connect` to
+`20.205.243.166:443` timed out while a `tls.connect` to the same IP with `servername: 'github.com'`
+completed with `authorized: true` and TLS 1.3. An intermittent block is worse than a solid one, because a
+single success is not evidence that the path works.
+
+### What this means in practice, so the next session does not repeat it
+
+* **`git clone` / `git fetch` / `git push` over HTTPS do not work on this host.** Do not build a plan
+  around them and do not retry them hoping for a different result.
+* **The working path to materialise the repository is a tarball from `codeload`**:
+  `https://codeload.github.com/TwinsEarth/dsh-windows2macos/tar.gz/refs/heads/main`, unpacked with
+  `tar --strip-components=1` into a directory that is then `git init`-ed. That yields a real work tree
+  containing exactly `main`, which is what `fleet-sync` needs.
+* **Publishing from this host goes through the REST API**, not through git. Every release so far was
+  pushed that way.
+* **The consequence to state plainly:** this host can *pull* the truth and can *run* the sync machinery, but
+  it cannot *push* over git. A round that needs a commit published must use the API, and a round that needs
+  `fleet-sync` exercised must do it against a local bare remote — which is a real test of the state
+  machine, and is **not** a test of the network.
+
+### Why this is a rule and not a note
+
+The first two attempts at "make Windows a git participant" assumed the failure was a configuration problem
+and tried proxy settings and retries. Both were wrong, and both cost a round. **The measurements above are
+cheaper to read than to repeat.**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twinsearth/w2m-dsh-plugin",
-  "version": "0.10.4",
+  "version": "0.10.5",
   "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",
@@ -29,6 +29,7 @@
     "CHANGELOG.md",
     "HANDOFF.md",
     "ROADMAP.md",
+    "FLEET-RULES.md",
     "LICENSE",
     "PROTOCOL.md",
     "PROTOCOL-v0.1.2.md",

package/src/plugin/tools.mjs

@@ -185,7 +185,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.10.4';
+const PLUGIN_VERSION = '0.10.5';
 
 /** How long any single HTTP call may take before it is aborted, in milliseconds. */
 const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;