npm - @twinsearth/w2m-dsh-plugin - Versions diffs - 0.10.2 → 0.10.4 - Mend

@twinsearth/w2m-dsh-plugin 0.10.2 → 0.10.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/CHANGELOG.md +81 -0
package/package.json +5 -4
package/src/agent/exit-channel.mjs +242 -0
package/src/agent/health.mjs +11 -4
package/src/plugin/tools.mjs +1 -1

package/CHANGELOG.md CHANGED Viewed

@@ -4,6 +4,87 @@ 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.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.**
+Found on a real machine, not by reading the code.
+`sample()` on macOS was scanning `/Users` for files that grow. On a developer machine that is hundreds of
+thousands of files, and the symptom was not "slow" but **total failure**: the health suite exceeded the
+fleet's own ~50-second lease ceiling and the task expired with `exit_code: null` and no result at all.
+A monitoring tool that times out because it is too expensive to monitor is worse than no monitoring,
+because **the timeout looks like a machine problem**. The contrast that identified it, measured on the same
+host minutes apart:
+| Command | Time | Result |
+|---|---|---|
+| `node -e "process.exit(1)"` | 8 s | `exit_code: 1` — the machinery was fine |
+| `health.test.mjs` (before) | > 50 s | expired, no result |
+| the same suite (authoring host) | 280 ms | pass |
+`/Users` is replaced by `/Library/Logs`, which is where an unbounded system writer actually writes. The rule
+this file already stated — that a health check must not be a load source — was written in the module header
+while the path list violated it, which is the useful part of the lesson: the principle was written down and
+still not applied to the one line that needed it.
+Sampling now costs 53 ms. 20 tests, 0 failures.
 ## [0.10.2] — 2026-10-15
 **Tiered storage — temporary, compressed, permanent, and the two kinds of knowledge that persist forever.**

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@twinsearth/w2m-dsh-plugin",
-  "version": "0.10.2",
+  "version": "0.10.4",
   "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",
@@ -112,13 +112,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 +133,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 ADDED Viewed

@@ -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/agent/health.mjs CHANGED Viewed

@@ -48,13 +48,20 @@ export const LOG_GROWTH_WARN_BYTES_PER_DAY = 1 * GB;
 /**
  * Which paths are worth checking for growth, by platform.
  *
- * Deliberately short. A health check that walks a whole filesystem is itself a load source, and the
- * incident was caused by *two* files rather than by a general untidiness — so the check names the places
- * where an unbounded writer has actually been observed.
+ * Deliberately short, and deliberately **not including a user's home directory**.
+ *
+ * A health check that walks a whole filesystem is itself a load source, and this list got that wrong on the
+ * first attempt: macOS was given `/Users`, and on a developer machine that is hundreds of thousands of files.
+ * The symptom appeared on a real machine as a health check that **exceeded the fleet's own ~50-second lease
+ * ceiling** and expired with no result at all — a monitoring tool timing out because it was too expensive to
+ * monitor. On the machine that wrote it, the same suite runs in 280 ms.
+ *
+ * So each entry is a place where an unbounded writer has actually been observed, which is what the 14.7
+ * GB/day incident was: two files in `/var/log`, not a general untidiness.
  */
 export const LOG_PATHS = Object.freeze({
   linux: ['/var/log', '/var/lib/w2m', '/tmp'],
-  darwin: ['/var/log', '/tmp', '/Users'],
+  darwin: ['/var/log', '/Library/Logs', '/tmp'],
   win32: ['C:\\Windows\\Logs', 'C:\\Windows\\Temp'],
 });

package/src/plugin/tools.mjs CHANGED Viewed

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