@twinsearth/w2m-dsh-plugin 0.10.3 → 0.10.5

package/CHANGELOG.md

@@ -4,6 +4,120 @@ 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.**
+
+### Why this exists, stated without euphemism
+
+The relay carries a per-machine `exit_code` faithfully and carries **no stdout at all**. That is a
+deliberate property of the ledger and the right design for a system whose job is to say whether machines
+agree — but the consequence is that an orchestrator can learn *that* a task failed and never *why*, and on
+this fleet that cost several rounds: a health check returning a real verdict was indistinguishable from one
+that crashed, because both produce a number and nothing else.
+
+Every channel that would carry text is unavailable here. The relay host's SSH and its sink are refused, an
+inbound receiver on the orchestrator never received a single connection, and a machine's `allowedCommands`
+may permit only a narrow set of commands. What has worked on every machine every time is the exit status. So
+this encodes bytes into exit codes. It is slow and it is ugly, and both are the point: **a diagnostic that
+arrives slowly is worth more than one that never arrives.**
+
+### The two design choices that are not arbitrary
+
+- **`126` and `127` never carry data.** Shells write them for "not executable" and "not found", so a real
+  127 and a data 127 would be indistinguishable and the reader would investigate the wrong failure. The
+  alphabet is therefore a mapping over `1..125` and `128..253`, not a constant offset — the first version
+  used `value + 1` across the whole range and its own test caught the collision.
+- **Truncation is not completion.** `254` ends the message and `255` says the sender failed. A channel that
+  stopped mid-message must not be read as a whole message, because that turns "the machine stopped talking"
+  into "the machine said this" with no way for the reader to tell.
+
+### Three failed fixes, and what actually located the bug
+
+`encodeBytes` emits remainders as it divides, so its output is **least significant first**; the decoder's
+Horner accumulator consumes digits **most significant first**. Feeding one into the other inverts the
+message, and it presents as byte-order corruption rather than reversal — `"first"` came back as
+`"Y~\u0010\u0018\u00fc"`.
+
+Two attempts to fix it failed because they were fixing the wrong half: a stray `.reverse()` was added to the
+*output* buffer, then removed, then removed again, while the real fault was that the *input* needed
+reversing. The first attempt also had a genuine second bug — the encoder mutated the array it was iterating
+— which masked the first. What settled it was computing the digits with `BigInt` and comparing: `encodeBytes`
+matched the reference exactly, which located the fault on the decode side and in the input order rather than
+the output.
+
+### What is documented rather than papered over
+
+Leading NUL bytes are not recoverable: they do not change the number, so `[0, 0, 1]` and `[1]` are the same
+value and the same digit list. Recovering them needs a length declared on the wire, and this channel carries
+text. That is asserted in the suite, because a future reader will otherwise treat it as a bug and add a
+length prefix that changes the wire format for every existing message.
+
+A 29-byte verdict costs 30 dispatches. `costOf()` reports this so a caller can see that a log file is not
+worth sending this way — and fix the real channel instead.
+
+**17 tests, 0 failures.**
+
 ## [0.10.3] — 2026-10-15
 
 **Fix: the macOS health check walked a user's home directory, and timed out instead of reporting.**

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.3",
+  "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",
@@ -112,13 +113,13 @@
     }
   },
   "scripts": {
-    "test": "node --test --test-force-exit test/relay.test.mjs test/broadcast.test.mjs test/agent.test.mjs test/authority.test.mjs test/blocks.test.mjs test/approval-index.test.mjs test/fleet-sync.test.mjs test/health.test.mjs test/storage.test.mjs test/memory.test.mjs test/tools.test.mjs  test/claims.test.mjs test/fleet-target.test.mjs test/client-bundle.test.mjs test/schedule.test.mjs test/auto-update.test.mjs test/update-source.test.mjs test/update-install.test.mjs test/update-wiring.test.mjs test/signing.test.mjs test/stress.test.mjs test/shared-config.test.mjs test/metrics.test.mjs test/metrics-route.test.mjs test/tool-cards.test.mjs test/p2p-stun.test.mjs test/p2p-transport.test.mjs test/p2p-signaling.test.mjs test/p2p-node.test.mjs test/p2p-transport-fields.test.mjs test/p2p-plugin.test.mjs test/p2p-crypto.test.mjs test/stun-server.test.mjs test/loader-entry.test.mjs test/mdns-wire.test.mjs test/mdns-discover.test.mjs test/chatops-approval.test.mjs test/chatops-policy.test.mjs test/chatops-file-safety.test.mjs test/chatops-outbound-queue.test.mjs test/chatops-commands.test.mjs test/chatops-bridge.test.mjs test/chatops-config-route.test.mjs test/chatops-apply.test.mjs test/chatops-ilink-contract.test.mjs test/chatops-fleet.test.mjs test/chatops-account.test.mjs test/chatops-auth.test.mjs test/chatops-fleet-scope.test.mjs test/chatops-handoff.test.mjs test/chatops-fleet-wiring.test.mjs test/chatops-fleet-live.test.mjs test/chatops-takeover.test.mjs test/chatops-device-signing.test.mjs test/chatops-relay-verify.test.mjs test/chatops-durability.test.mjs test/chatops-run-command.test.mjs test/secrets-guard.test.mjs test/chatops-ilink-fleet-bridge.test.mjs test/chatops-fleet-join.test.mjs",
+    "test": "node --test --test-force-exit test/relay.test.mjs test/broadcast.test.mjs test/agent.test.mjs test/authority.test.mjs test/blocks.test.mjs test/approval-index.test.mjs test/fleet-sync.test.mjs test/health.test.mjs test/storage.test.mjs test/exit-channel.test.mjs test/memory.test.mjs test/tools.test.mjs  test/claims.test.mjs test/fleet-target.test.mjs test/client-bundle.test.mjs test/schedule.test.mjs test/auto-update.test.mjs test/update-source.test.mjs test/update-install.test.mjs test/update-wiring.test.mjs test/signing.test.mjs test/stress.test.mjs test/shared-config.test.mjs test/metrics.test.mjs test/metrics-route.test.mjs test/tool-cards.test.mjs test/p2p-stun.test.mjs test/p2p-transport.test.mjs test/p2p-signaling.test.mjs test/p2p-node.test.mjs test/p2p-transport-fields.test.mjs test/p2p-plugin.test.mjs test/p2p-crypto.test.mjs test/stun-server.test.mjs test/loader-entry.test.mjs test/mdns-wire.test.mjs test/mdns-discover.test.mjs test/chatops-approval.test.mjs test/chatops-policy.test.mjs test/chatops-file-safety.test.mjs test/chatops-outbound-queue.test.mjs test/chatops-commands.test.mjs test/chatops-bridge.test.mjs test/chatops-config-route.test.mjs test/chatops-apply.test.mjs test/chatops-ilink-contract.test.mjs test/chatops-fleet.test.mjs test/chatops-account.test.mjs test/chatops-auth.test.mjs test/chatops-fleet-scope.test.mjs test/chatops-handoff.test.mjs test/chatops-fleet-wiring.test.mjs test/chatops-fleet-live.test.mjs test/chatops-takeover.test.mjs test/chatops-device-signing.test.mjs test/chatops-relay-verify.test.mjs test/chatops-durability.test.mjs test/chatops-run-command.test.mjs test/secrets-guard.test.mjs test/chatops-ilink-fleet-bridge.test.mjs test/chatops-fleet-join.test.mjs",
     "test:e2e": "node --test --test-force-exit test/e2e.test.mjs test/crossnetwork.test.mjs test/signing-e2e.test.mjs test/outbound-only.test.mjs test/recovery.test.mjs test/pipeline-e2e.test.mjs test/p2p-agent.test.mjs",
     "test:relay": "node --test --test-force-exit test/relay.test.mjs",
     "test:agent": "node --test --test-force-exit test/agent.test.mjs test/memory.test.mjs",
     "test:tools": "node --test --test-force-exit test/tools.test.mjs",
     "test:crossnetwork": "node --test --test-force-exit test/crossnetwork.test.mjs",
-    "test:all": "node --test --test-force-exit test/relay.test.mjs test/broadcast.test.mjs test/agent.test.mjs test/authority.test.mjs test/blocks.test.mjs test/approval-index.test.mjs test/fleet-sync.test.mjs test/health.test.mjs test/storage.test.mjs test/memory.test.mjs test/tools.test.mjs  test/claims.test.mjs test/fleet-target.test.mjs test/client-bundle.test.mjs test/schedule.test.mjs test/auto-update.test.mjs test/update-source.test.mjs test/update-install.test.mjs test/update-wiring.test.mjs test/signing.test.mjs test/stress.test.mjs test/e2e.test.mjs test/crossnetwork.test.mjs test/signing-e2e.test.mjs test/outbound-only.test.mjs test/recovery.test.mjs test/pipeline-e2e.test.mjs test/shared-config.test.mjs test/metrics.test.mjs test/metrics-route.test.mjs test/tool-cards.test.mjs test/p2p-stun.test.mjs test/p2p-transport.test.mjs test/p2p-signaling.test.mjs test/p2p-node.test.mjs test/p2p-transport-fields.test.mjs test/p2p-plugin.test.mjs test/p2p-agent.test.mjs test/stun-server.test.mjs test/loader-entry.test.mjs test/mdns-wire.test.mjs test/mdns-discover.test.mjs test/p2p-crypto.test.mjs test/chatops-approval.test.mjs test/chatops-policy.test.mjs test/chatops-file-safety.test.mjs test/chatops-outbound-queue.test.mjs test/chatops-commands.test.mjs test/chatops-bridge.test.mjs test/chatops-config-route.test.mjs test/chatops-apply.test.mjs test/chatops-ilink-contract.test.mjs test/chatops-fleet.test.mjs test/chatops-account.test.mjs test/chatops-auth.test.mjs test/chatops-fleet-scope.test.mjs test/chatops-handoff.test.mjs test/chatops-fleet-wiring.test.mjs test/chatops-fleet-live.test.mjs test/chatops-takeover.test.mjs test/chatops-device-signing.test.mjs test/chatops-relay-verify.test.mjs test/chatops-durability.test.mjs test/chatops-run-command.test.mjs test/secrets-guard.test.mjs test/chatops-ilink-fleet-bridge.test.mjs test/chatops-fleet-join.test.mjs",
+    "test:all": "node --test --test-force-exit test/relay.test.mjs test/broadcast.test.mjs test/agent.test.mjs test/authority.test.mjs test/blocks.test.mjs test/approval-index.test.mjs test/fleet-sync.test.mjs test/health.test.mjs test/storage.test.mjs test/exit-channel.test.mjs test/memory.test.mjs test/tools.test.mjs  test/claims.test.mjs test/fleet-target.test.mjs test/client-bundle.test.mjs test/schedule.test.mjs test/auto-update.test.mjs test/update-source.test.mjs test/update-install.test.mjs test/update-wiring.test.mjs test/signing.test.mjs test/stress.test.mjs test/e2e.test.mjs test/crossnetwork.test.mjs test/signing-e2e.test.mjs test/outbound-only.test.mjs test/recovery.test.mjs test/pipeline-e2e.test.mjs test/shared-config.test.mjs test/metrics.test.mjs test/metrics-route.test.mjs test/tool-cards.test.mjs test/p2p-stun.test.mjs test/p2p-transport.test.mjs test/p2p-signaling.test.mjs test/p2p-node.test.mjs test/p2p-transport-fields.test.mjs test/p2p-plugin.test.mjs test/p2p-agent.test.mjs test/stun-server.test.mjs test/loader-entry.test.mjs test/mdns-wire.test.mjs test/mdns-discover.test.mjs test/p2p-crypto.test.mjs test/chatops-approval.test.mjs test/chatops-policy.test.mjs test/chatops-file-safety.test.mjs test/chatops-outbound-queue.test.mjs test/chatops-commands.test.mjs test/chatops-bridge.test.mjs test/chatops-config-route.test.mjs test/chatops-apply.test.mjs test/chatops-ilink-contract.test.mjs test/chatops-fleet.test.mjs test/chatops-account.test.mjs test/chatops-auth.test.mjs test/chatops-fleet-scope.test.mjs test/chatops-handoff.test.mjs test/chatops-fleet-wiring.test.mjs test/chatops-fleet-live.test.mjs test/chatops-takeover.test.mjs test/chatops-device-signing.test.mjs test/chatops-relay-verify.test.mjs test/chatops-durability.test.mjs test/chatops-run-command.test.mjs test/secrets-guard.test.mjs test/chatops-ilink-fleet-bridge.test.mjs test/chatops-fleet-join.test.mjs",
     "pack": "node scripts/pack.mjs",
     "verify:join": "node scripts/verify-join.mjs",
     "lint": "eslint .",
@@ -133,7 +134,8 @@
     "test:approval-index": "node --test --test-force-exit test/approval-index.test.mjs",
     "test:fleet-sync": "node --test --test-force-exit test/fleet-sync.test.mjs",
     "test:health": "node --test --test-force-exit test/health.test.mjs",
-    "test:storage": "node --test --test-force-exit test/storage.test.mjs"
+    "test:storage": "node --test --test-force-exit test/storage.test.mjs",
+    "test:exit-channel": "node --test --test-force-exit test/exit-channel.test.mjs"
   },
   "keywords": [
     "dsh-bundle",

package/src/agent/exit-channel.mjs

@@ -0,0 +1,242 @@
+/**
+ * A result channel over exit codes, for machines whose text cannot be read back.
+ *
+ * ## The problem this solves, stated honestly
+ *
+ * The relay carries a per-machine `exit_code` faithfully and carries **no stdout at all** — that is a
+ * deliberate property of the ledger, not a bug, and it is the right design for a system whose job is to say
+ * whether machines agree. The consequence is that an orchestrator can learn *that* a task failed and never
+ * *why*, and on this fleet that cost several rounds: a health check that returned a real verdict was
+ * indistinguishable from one that crashed, because both produce a number and nothing else.
+ *
+ * The channels that would carry text are all unavailable here: the relay host's SSH and its sink are
+ * refused, an inbound receiver on the orchestrator never received a single connection, and a machine's
+ * `allowedCommands` may permit only a narrow set of commands. What is left is the one thing that has worked
+ * on every machine every time: **the exit status**.
+ *
+ * So this encodes bytes into exit codes. It is slow and it is ugly, and both of those are the point — it is
+ * the channel of last resort, and a diagnostic that arrives slowly is worth more than a diagnostic that
+ * never arrives.
+ *
+ * ## Why base 251 and not base 256
+ *
+ * Exit codes are unsigned bytes *in principle* and considerably less than that in practice. `0` is taken:
+ * it is what a successful command returns, so it must mean "the message is finished" rather than "the byte
+ * is zero". Codes above 125 are unreliable — `126` and `127` are written by shells for "not executable"
+ * and "not found", and a value that collides with a shell's own error is a diagnostic that reads as a
+ * different failure. So the payload alphabet is **1..251**, which is 251 symbols, and a byte is carried as
+ * `value + 1`.
+ *
+ * That leaves `252..255` free for framing, and they are used as unambiguous terminators, because "the
+ * channel stopped" and "the message ended" must not look alike. A truncated report read as a complete one
+ * is the failure mode that makes a diagnostic worse than none.
+ *
+ * ## What is deliberately absent
+ *
+ * No compression, no encryption, no resumption. Each would be a way to make the transport cleverer than the
+ * thing it transports, and the whole reason this exists is that the clever transports were the ones that
+ * did not work. A caller with a large payload should fix the real channel instead of using this one.
+ */
+
+/**
+ * The payload alphabet: 251 symbols, carried by the 253 exit codes that are safe to write.
+ *
+ * Codes `1..125` and `128..253` carry data; `126`, `127`, `254` and `255` do not. The two omissions are
+ * deliberate and are the whole reason this is a mapping rather than a constant offset:
+ *
+ *   * **`126` and `127` are written by shells** for "not executable" and "not found". If they could carry
+ *     data, a real 127 from a missing interpreter and a data 127 would be indistinguishable and the reader
+ *     would investigate the wrong failure. The first version of this module used `value + 1` across the
+ *     whole range and its own test caught the collision.
+ *   * **`254` and `255` carry the framing** that makes "the message ended" distinguishable from "the channel
+ *     died", and `0` is reserved because a successful command returns it.
+ */
+export const SYMBOL_COUNT = 251;
+
+/** Exit code for symbol `value`: skip the two shell-owned codes. */
+export function codeForSymbol(value) {
+  if (!Number.isInteger(value) || value < 0 || value >= SYMBOL_COUNT) {
+    throw new RangeError(`symbol ${value} is outside 0..${SYMBOL_COUNT - 1}`);
+  }
+  const code = value + 1;
+  return code < 126 ? code : code + 2;
+}
+
+/** Symbol carried by an exit code, or `null` when the code is not a payload digit. */
+export function symbolForCode(code) {
+  if (!Number.isInteger(code)) return null;
+  if (code >= 1 && code <= 125) return code - 1;
+  if (code >= 128 && code <= 253) return code - 3;
+  return null;
+}
+
+/** Frame codes, chosen from the exit codes that carry no payload. */
+export const FRAME = Object.freeze({
+  /** The message ended cleanly. */
+  END: 254,
+  /** The sender failed and is saying so rather than ending. */
+  ERROR: 255,
+  /** Written by a shell for "not executable"; never emitted as data. */
+  SHELL_NOT_EXECUTABLE: 126,
+  /** Written by a shell for "not found"; never emitted as data. */
+  SHELL_NOT_FOUND: 127,
+});
+
+/** Exit code used by a sender that finished the whole message. */
+export const DONE = FRAME.END;
+
+/**
+ * Split bytes into base-251 digits, least significant first.
+ *
+ * A big integer would be the obvious representation and is the wrong one: `BigInt` arithmetic over a
+ * multi-kilobyte payload is slower than the digit loop and produces a value whose length is not obviously
+ * related to the input's. Here each output digit carries a known amount of text, so a truncated message is
+ * detectable by counting.
+ *
+ * The loop below is long division of `input` (read as a base-256 number) by 251, repeated until the
+ * quotient is zero, collecting remainders least-significant first. Each pass builds a **new** quotient array
+ * and rebinds it, rather than clearing and refilling the array being iterated -- the first version of this
+ * function did the latter, and mutating a collection while iterating it produced nine failing round-trips
+ * out of eighteen, including single bytes.
+ *
+ * @param {Buffer} bytes
+ * @returns {number[]} values in `0..250`
+ */
+export function encodeBytes(bytes) {
+  const input = Buffer.isBuffer(bytes) ? bytes : Buffer.from(String(bytes), 'utf8');
+  const digits = [];
+  let current = Array.from(input);
+  while (!(current.length === 0 || (current.length === 1 && current[0] === 0))) {
+    const quotient = [];
+    let remainder = 0;
+    for (const byte of current) {
+      const value = remainder * 256 + byte;
+      const q = Math.floor(value / SYMBOL_COUNT);
+      remainder = value % SYMBOL_COUNT;
+      // Leading zeros in the quotient are dropped, because the divisor never produces a meaningful one and
+      // keeping them would make the loop's termination depend on the input's length rather than its value.
+      if (quotient.length > 0 || q > 0) quotient.push(q);
+    }
+    digits.push(remainder);
+    current = quotient;
+  }
+  return digits;
+}
+
+/**
+ * Rebuild bytes from base-251 digits, least significant first.
+ *
+ * ## The direction mismatch that made this wrong three times
+ *
+ * `encodeBytes` emits remainders as it divides, so its output is **least significant first**. The
+ * accumulator below is Horner's rule, which consumes digits **most significant first**. Feeding one into the
+ * other directly inverts the message, and it does so in a way that looks like byte-order corruption rather
+ * than a reversal: `"first"` came back as `"Y~\u0010\u0018\u00fc"`, the right multiset of bytes in the wrong
+ * order.
+ *
+ * Two attempts to fix that failed because they were fixing the wrong half -- first a stray `.reverse()` on
+ * the *output* buffer was added and removed, and then it was removed again, while the actual problem was
+ * that the *input* needed reversing. The reference check that settled it was computing the digits with
+ * `BigInt` and comparing: `encodeBytes` matched the reference exactly, which located the fault on the decode
+ * side and in the input order rather than the output.
+ *
+ * @param {number[]} digits least significant first, as `encodeBytes` produces
+ * @returns {Buffer}
+ */
+export function decodeBytes(digits) {
+  let current = [0];
+  for (const digit of [...digits].reverse()) {
+    let carry = digit;
+    const next = [];
+    for (const value of current) {
+      const total = value * SYMBOL_COUNT + carry;
+      next.push(total % 256);
+      carry = Math.floor(total / 256);
+    }
+    while (carry > 0) {
+      next.push(carry % 256);
+      carry = Math.floor(carry / 256);
+    }
+    current = next;
+  }
+  // Trim high-order zero bytes, which the multiplication produces for any value that does not fill its last
+  // limb. This is also why leading NUL bytes are not recoverable: a leading zero does not change the number,
+  // so `[0, 0, 1]` and `[1]` are the same value and the same digit list. Recovering them would need a length
+  // declared on the wire, and this channel carries text.
+  while (current.length > 1 && current[current.length - 1] === 0) current.pop();
+  if (current.length === 1 && current[0] === 0) return Buffer.alloc(0);
+  // Little-endian in, little-endian out: reverse once, here, at the boundary.
+  return Buffer.from(current.reverse());
+}
+
+/**
+ * Turn a report into the exit codes that carry it, ending with the end frame.
+ *
+ * The terminator is part of the encoding rather than a convention the caller remembers, because a caller
+ * who forgets it produces a receiver that waits forever for a message that already finished.
+ *
+ * @param {string|Buffer} report
+ * @returns {number[]} exit codes, in order
+ */
+export function toExitCodes(report) {
+  return [...encodeBytes(report).map(codeForSymbol), DONE];
+}
+
+/**
+ * Decode exit codes back into a report.
+ *
+ * Distinguishes three outcomes, because they need different responses: a complete message, a message that
+ * stopped early, and a sender that reported its own failure. Collapsing them is how "truncated" is read as
+ * "complete" and a half-answer is believed.
+ *
+ * @param {number[]} codes
+ * @returns {{ok: true, text: string, bytes: number} | {ok: false, reason_code: string, text: string|null, detail: string}}
+ */
+export function fromExitCodes(codes) {
+  const digits = [];
+  for (let i = 0; i < codes.length; i += 1) {
+    const code = codes[i];
+    if (code === FRAME.END) {
+      // Everything after a clean end is ignored rather than appended: a sender that emitted more than one
+      // terminator is confused, and guessing which message was intended is not this function's job.
+      const bytes = decodeBytes(digits);
+      return { ok: true, text: bytes.toString('utf8'), bytes: bytes.length };
+    }
+    if (code === FRAME.ERROR) {
+      const partial = digits.length > 0 ? decodeBytes(digits).toString('utf8') : null;
+      return { ok: false, reason_code: 'SENDER_REPORTED_ERROR', text: partial, detail: 'the sender stopped and said so rather than ending the message' };
+    }
+    const symbol = symbolForCode(code);
+    if (symbol === null) {
+      // A code outside the alphabet. `126` and `127` land here, and naming them matters: they are what a
+      // shell writes when the command never ran at all, which is a different diagnosis from a bad digit.
+      const why = code === FRAME.SHELL_NOT_EXECUTABLE
+        ? 'exit code 126 is written by a shell for "not executable": the command never ran'
+        : code === FRAME.SHELL_NOT_FOUND
+          ? 'exit code 127 is written by a shell for "not found": the command never ran'
+          : `exit code ${code} at position ${i} is outside the payload alphabet`;
+      return { ok: false, reason_code: 'EXIT_CODE_OUT_OF_ALPHABET', text: null, detail: why };
+    }
+    digits.push(symbol);
+  }
+  // Ran out of codes without a terminator. This is the case worth being loud about.
+  const partial = digits.length > 0 ? decodeBytes(digits).toString('utf8') : null;
+  return {
+    ok: false,
+    reason_code: 'TRUNCATED',
+    text: partial,
+    detail: `the channel ended after ${codes.length} code(s) with no end frame; the message is incomplete and must not be read as a whole`,
+  };
+}
+
+/**
+ * How many dispatches a report costs.
+ *
+ * Reported rather than estimated at the call site, because the honest answer is what decides whether this
+ * channel is usable for a given payload: a one-line verdict is a handful of codes, and a log file is not
+ * worth sending this way at all.
+ */
+export function costOf(report) {
+  const codes = toExitCodes(report);
+  return { exit_codes: codes.length, bytes: Buffer.byteLength(String(report), 'utf8') };
+}

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.3';
+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;