@rubytech/create-maxy-code 0.1.286 → 0.1.288

package/dist/__tests__/cloudflared-slice.test.js

@@ -1,13 +1,14 @@
 // Task 602 — cloudflared.slice unit emitted at install time.
-// Every cloudflared-<brand>.scope spawned by resume-tunnel.sh drops under
+// Every cloudflared-<brand>.service spawned by resume-tunnel.sh drops under
 // this slice for cohort observability via `systemctl --user status cloudflared.slice`.
+// (Task 757 changed the per-brand unit from a scope to a supervised service.)
 import test from "node:test";
 import assert from "node:assert/strict";
 import { buildCloudflaredSliceUnitFile } from "../port-resolution.js";
 test("buildCloudflaredSliceUnitFile emits a valid systemd slice unit", () => {
     const unit = buildCloudflaredSliceUnitFile();
     assert.match(unit, /^\[Unit\]$/m);
-    assert.match(unit, /^Description=Cloudflare tunnel scopes \(Task 602\)$/m);
+    assert.match(unit, /^Description=Cloudflare tunnel connectors \(Task 602\)$/m);
     assert.match(unit, /^\[Slice\]$/m);
     assert.match(unit, /^\[Install\]$/m);
     assert.match(unit, /^WantedBy=default\.target$/m);

package/dist/__tests__/cloudflared-version-pin.test.js

@@ -0,0 +1,24 @@
+// Task 757 — the cloudflared binary version is installer-owned and pinned.
+// The connector runs with --no-autoupdate (resume-tunnel.sh), so it never
+// self-replaces; the only way the binary version moves is bumping the pin in
+// installCloudflared and republishing the installer. This guards against a
+// regression back to the `releases/latest/download/` URL that let the binary
+// drift (the 2026-06-10 realagent-code outage root cause).
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+// The test runner compiles src -> dist and runs dist/__tests__/*.test.js, so
+// read the compiled sibling index.js; the URL string literal survives tsc.
+const here = dirname(fileURLToPath(import.meta.url));
+const compiled = readFileSync(join(here, "../index.js"), "utf8");
+test("cloudflared version is pinned to 2026.6.0", () => {
+    assert.match(compiled, /CLOUDFLARED_VERSION\s*=\s*"2026\.6\.0"/);
+});
+test("the .deb fetch URL is wired to the pinned version constant", () => {
+    assert.match(compiled, /releases\/download\/\$\{CLOUDFLARED_VERSION\}\/cloudflared-linux-/);
+});
+test("cloudflared .deb fetch no longer uses the drifting latest URL", () => {
+    assert.doesNotMatch(compiled, /releases\/latest\/download\/cloudflared-linux-/);
+});

package/dist/__tests__/samba-provision.test.js

@@ -6,7 +6,7 @@
 // style and runs under `node --test dist/__tests__/*.test.js` after build.
 import test from "node:test";
 import assert from "node:assert/strict";
-import { renderBrandStanza, renderGlobalSection, renderFullSmbConf, pickLanInterface, mergeSmbConf, removeBrandStanza, hasAnyBrandStanza, formatSambaMarker, SAMBA_STEPS, } from "../samba-provision.js";
+import { renderBrandStanza, renderGlobalSection, renderFullSmbConf, isPrivateIPv4, pickBindDecision, mergeSmbConf, removeBrandStanza, hasAnyBrandStanza, formatSambaMarker, SAMBA_STEPS, SAMBA_ENABLE_UNITS, } from "../samba-provision.js";
 // ---------------------------------------------------------------------------
 // Fixtures
 // ---------------------------------------------------------------------------
@@ -34,29 +34,77 @@ const PI_USB0_FALLBACK = {
     lo: [{ address: "127.0.0.1", netmask: "255.0.0.0", family: "IPv4", mac: "00:00:00:00:00:00", internal: true, cidr: "127.0.0.1/8" }],
     usb0: [{ address: "172.17.0.2", netmask: "255.255.255.0", family: "IPv4", mac: "22:22:22:22:22:22", internal: false, cidr: "172.17.0.2/24" }],
 };
+// Hetzner shape: the only non-loopback interface is eth0 carrying the public
+// IP directly (/32, no private LAN). Binding `lo eth0` here would expose smbd
+// to the public internet — the defect Task 755 fixes by binding loopback-only.
+const HETZNER_PUBLIC_ETH0_ONLY = {
+    lo: [{ address: "127.0.0.1", netmask: "255.0.0.0", family: "IPv4", mac: "00:00:00:00:00:00", internal: true, cidr: "127.0.0.1/8" }],
+    eth0: [{ address: "167.233.21.246", netmask: "255.255.255.255", family: "IPv4", mac: "96:00:00:00:00:01", internal: false, cidr: "167.233.21.246/32" }],
+};
+// Dual-homed box: a public eth0 plus a private wireguard/LAN interface. The
+// private interface exists, so the bind stays LAN (operator confirmation,
+// Task 755): loopback-only fires only when NO private interface exists.
+const MIXED_PUBLIC_AND_PRIVATE = {
+    lo: [{ address: "127.0.0.1", netmask: "255.0.0.0", family: "IPv4", mac: "00:00:00:00:00:00", internal: true, cidr: "127.0.0.1/8" }],
+    eth0: [{ address: "178.105.251.82", netmask: "255.255.255.255", family: "IPv4", mac: "96:00:00:00:00:02", internal: false, cidr: "178.105.251.82/32" }],
+    wg0: [{ address: "10.8.0.3", netmask: "255.255.255.0", family: "IPv4", mac: "00:00:00:00:00:00", internal: false, cidr: "10.8.0.3/24" }],
+};
+// ---------------------------------------------------------------------------
+// isPrivateIPv4 — RFC1918 / CGNAT / link-local classification
+// ---------------------------------------------------------------------------
+test("isPrivateIPv4: RFC1918 ranges are private", () => {
+    assert.equal(isPrivateIPv4("10.0.0.5"), true);
+    assert.equal(isPrivateIPv4("172.16.0.1"), true);
+    assert.equal(isPrivateIPv4("172.31.255.254"), true);
+    assert.equal(isPrivateIPv4("192.168.1.50"), true);
+});
+test("isPrivateIPv4: CGNAT (100.64/10) and link-local (169.254/16) are private", () => {
+    assert.equal(isPrivateIPv4("100.64.0.1"), true);
+    assert.equal(isPrivateIPv4("100.127.255.254"), true);
+    assert.equal(isPrivateIPv4("169.254.1.1"), true);
+});
+test("isPrivateIPv4: routable public addresses are not private", () => {
+    assert.equal(isPrivateIPv4("167.233.21.246"), false);
+    assert.equal(isPrivateIPv4("178.105.251.82"), false);
+    assert.equal(isPrivateIPv4("8.8.8.8"), false);
+    // Boundary misses: 172.15/172.32 are outside the /12; 100.63/100.128 outside
+    // the CGNAT /10; 169.253/169.255 outside link-local.
+    assert.equal(isPrivateIPv4("172.15.0.1"), false);
+    assert.equal(isPrivateIPv4("172.32.0.1"), false);
+    assert.equal(isPrivateIPv4("100.63.255.255"), false);
+    assert.equal(isPrivateIPv4("100.128.0.0"), false);
+    assert.equal(isPrivateIPv4("169.253.0.1"), false);
+});
 // ---------------------------------------------------------------------------
-// pickLanInterface
+// pickBindDecision — private→LAN, public-only→loopback-only, none→none
 // ---------------------------------------------------------------------------
-test("pickLanInterface: wlan0 wins over eth0 when both present", () => {
-    assert.equal(pickLanInterface(PI_BOTH_IFACES), "wlan0");
+test("pickBindDecision: wlan0 wins over eth0 when both private", () => {
+    assert.deepEqual(pickBindDecision(PI_BOTH_IFACES), { kind: "lan", lanInterface: "wlan0" });
+});
+test("pickBindDecision: private wlan0 alone is a LAN bind", () => {
+    assert.deepEqual(pickBindDecision(PI_WLAN0_ONLY), { kind: "lan", lanInterface: "wlan0" });
 });
-test("pickLanInterface: wlan0 alone is picked", () => {
-    assert.equal(pickLanInterface(PI_WLAN0_ONLY), "wlan0");
+test("pickBindDecision: private eth0 alone is a LAN bind", () => {
+    assert.deepEqual(pickBindDecision(PI_ETH0_ONLY), { kind: "lan", lanInterface: "eth0" });
 });
-test("pickLanInterface: eth0 alone is picked", () => {
-    assert.equal(pickLanInterface(PI_ETH0_ONLY), "eth0");
+test("pickBindDecision: fallback to any non-loopback private IPv4 (usb0)", () => {
+    assert.deepEqual(pickBindDecision(PI_USB0_FALLBACK), { kind: "lan", lanInterface: "usb0" });
 });
-test("pickLanInterface: fallback to any non-loopback IPv4 (usb0)", () => {
-    assert.equal(pickLanInterface(PI_USB0_FALLBACK), "usb0");
+test("pickBindDecision: public-only host (Hetzner eth0 /32) binds loopback-only", () => {
+    assert.deepEqual(pickBindDecision(HETZNER_PUBLIC_ETH0_ONLY), { kind: "loopback-only" });
 });
-test("pickLanInterface: returns null when only loopback is present", () => {
-    assert.equal(pickLanInterface(PI_LO_ONLY), null);
+test("pickBindDecision: dual-homed (public eth0 + private wg0) binds to the private interface", () => {
+    assert.deepEqual(pickBindDecision(MIXED_PUBLIC_AND_PRIVATE), { kind: "lan", lanInterface: "wg0" });
 });
-test("pickLanInterface: returns null when the only non-loopback iface has no IPv4", () => {
+test("pickBindDecision: none when only loopback is present", () => {
+    assert.deepEqual(pickBindDecision(PI_LO_ONLY), { kind: "none" });
+});
+test("pickBindDecision: none when the only non-loopback iface has no IPv4", () => {
     // smbd cannot bind to an IPv6-only address with `interfaces = lo eth0` syntax
-    // unmodified; treat as no usable LAN interface so caller loud-fails rather
-    // than writing a broken smb.conf.
-    assert.equal(pickLanInterface(PI_IPV6_ONLY_LAN), null);
+    // unmodified; treat as no usable interface so the caller loud-fails rather
+    // than writing a broken smb.conf. Distinct from loopback-only, which still
+    // provisions a working (host-local) share.
+    assert.deepEqual(pickBindDecision(PI_IPV6_ONLY_LAN), { kind: "none" });
 });
 // ---------------------------------------------------------------------------
 // renderBrandStanza — exact spec match
@@ -115,6 +163,15 @@ test("renderGlobalSection binds to lo + LAN interface only", () => {
     // No `map to guest = ok` — guests are explicitly rejected as bad-user.
     assert.match(globals, /\n   map to guest = bad user\n/);
 });
+test("renderGlobalSection: loopback-only bind emits `interfaces = lo` with no second token", () => {
+    // Public-only host (Hetzner): lanInterface=null means bind smbd to loopback
+    // only, so the share is reachable solely via the box itself (SSH tunnel).
+    // `bind interfaces only = yes` still holds, so nothing else can connect.
+    const globals = renderGlobalSection({ lanInterface: null });
+    assert.match(globals, /\n   interfaces = lo\n/);
+    assert.doesNotMatch(globals, /\n   interfaces = lo \S/, "loopback-only must not name a second interface");
+    assert.match(globals, /\n   bind interfaces only = yes\n/);
+});
 // ---------------------------------------------------------------------------
 // renderFullSmbConf — composition order
 // ---------------------------------------------------------------------------
@@ -224,3 +281,14 @@ test("formatSambaMarker emits the `[install-invariant] samba-provision-<step> <s
     assert.equal(formatSambaMarker("user", "deferred reason=no-plaintext-pin"), "[install-invariant] samba-provision-user deferred reason=no-plaintext-pin");
     assert.equal(formatSambaMarker("units", "fail: Job for smbd.service failed"), "[install-invariant] samba-provision-units fail: Job for smbd.service failed");
 });
+// ---------------------------------------------------------------------------
+// SAMBA_ENABLE_UNITS — the units step must never enable nmbd (Task 755)
+// ---------------------------------------------------------------------------
+test("SAMBA_ENABLE_UNITS enables smbd only — nmbd is never started", () => {
+    // nmbd is the NetBIOS name service BSI flagged as a DDoS-reflection vector;
+    // nothing mounts the share by NetBIOS name (mDNS/LAN-IP only), so it is dead
+    // weight. The units step enables smbd alone. Uninstall still *disables* nmbd
+    // defensively to clean pre-fix boxes — that is a separate command vector.
+    assert.deepEqual([...SAMBA_ENABLE_UNITS], ["smbd"]);
+    assert.ok(!SAMBA_ENABLE_UNITS.includes("nmbd"), "nmbd must not be in the enable --now unit list");
+});

package/dist/index.js

@@ -18,7 +18,7 @@ import { decideChromiumAction, isSnapConfinedPath } from "./snap-chromium.js";
 import { classifyPortHolder } from "./preflight-port-classifier.js";
 import { parsePluginList, computeInstallActions, parseExternalPlugins, } from "./lib/plugin-install.js";
 import { findPremiumMcpDirs } from "./lib/premium-mcp-discover.js";
-import { pickLanInterface, mergeSmbConf, formatSambaMarker, } from "./samba-provision.js";
+import { pickBindDecision, mergeSmbConf, formatSambaMarker, SAMBA_ENABLE_UNITS, } from "./samba-provision.js";
 import { networkInterfaces, userInfo } from "node:os";
 const PAYLOAD_DIR = resolve(import.meta.dirname, "../payload");
 // Brand manifest — read from payload to derive all brand-specific installation values.
@@ -1599,6 +1599,13 @@ function installUv() {
         console.error("  WARNING: uv installed but uvx not on PATH — check $HOME/.local/bin");
     }
 }
+// Task 757 — cloudflared version is installer-owned and pinned. The connector
+// runs with --no-autoupdate (resume-tunnel.sh), so it never self-replaces; the
+// only way the binary version moves is bumping this pin and republishing the
+// installer. Fetching `latest` (the prior behaviour) let the binary drift at
+// install time and, combined with the connector's own auto-update, caused the
+// 2026-06-10 realagent-code tunnel outage.
+const CLOUDFLARED_VERSION = "2026.6.0";
 function installCloudflared() {
     if (commandExists("cloudflared")) {
         log("6", TOTAL, "Cloudflared already installed.");
@@ -1619,7 +1626,7 @@ function installCloudflared() {
     }
     const arch = isArm64() ? "arm64" : "amd64";
     const debPath = "/tmp/cloudflared.deb";
-    shellRetry("curl", ["-fSL", "--progress-bar", `https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-${arch}.deb`, "-o", debPath], { timeout: 120_000 }, 3, 10);
+    shellRetry("curl", ["-fSL", "--progress-bar", `https://github.com/cloudflare/cloudflared/releases/download/${CLOUDFLARED_VERSION}/cloudflared-linux-${arch}.deb`, "-o", debPath], { timeout: 120_000 }, 3, 10);
     console.log("  [privileged] dpkg -i");
     shell("dpkg", ["-i", debPath], { sudo: true });
     spawnSync("rm", ["-f", debPath]);
@@ -3180,11 +3187,12 @@ function installService() {
     writeFileSync(join(serviceDir, claudePtysSliceName), buildClaudePtysSliceUnitFile());
     logFile(`  ${claudePtysSliceName}: Task 250 slice for claude-session-*.scope cohort`);
     // Task 602 — write the brand-agnostic `cloudflared.slice` unit. Every
-    // cloudflared-<brand>.scope spawned by resume-tunnel.sh drops under this
-    // slice. Writing once per install is idempotent; daemon-reload below picks it up.
+    // cloudflared-<brand>.service spawned by resume-tunnel.sh drops under this
+    // slice (Task 757 changed the unit from a scope to a supervised service).
+    // Writing once per install is idempotent; daemon-reload below picks it up.
     const cloudflaredSliceName = "cloudflared.slice";
     writeFileSync(join(serviceDir, cloudflaredSliceName), buildCloudflaredSliceUnitFile());
-    logFile(`  ${cloudflaredSliceName}: Task 602 slice for cloudflared-*.scope cohort`);
+    logFile(`  ${cloudflaredSliceName}: Task 602 slice for cloudflared-*.service cohort`);
     // Task 600 — per-brand RSS sampler: a long-running user service that
     // periodically writes per-claude.exe RSS + aggregate RSS to disk.
     // Named per-brand (BRAND.hostname prefix) so two brands on the same
@@ -3512,7 +3520,7 @@ WantedBy=multi-user.target
 //   conf  — write the brand stanza + LAN-only globals to /etc/samba/smb.conf
 //   user  — smbpasswd the install-owner Linux user; deferred at install time
 //           on fresh Pi installs (no plaintext PIN until the operator runs set-pin)
-//   units — systemctl enable --now smbd nmbd
+//   units — systemctl enable --now smbd (nmbd is never enabled; Task 755)
 //
 // The platform's set-pin route handler closes the deferral loop by running
 // `smbpasswd -a -s <install-owner>` inline whenever the PIN is set or
@@ -3563,12 +3571,19 @@ function provisionSamba() {
         emitSambaMarker("apt", `fail: ${stderr}`);
         throw err;
     }
-    // Step 2 — write the brand stanza into /etc/samba/smb.conf.
-    const lanInterface = pickLanInterface(networkInterfaces());
-    if (!lanInterface) {
+    // Step 2 — write the brand stanza into /etc/samba/smb.conf. Classify the
+    // host's interfaces (Task 755): a private LAN interface → bind `lo <iface>`;
+    // a public-only host (Hetzner) → bind loopback-only (`lanInterface = null`)
+    // so the share is reachable only from the box itself; no non-loopback IPv4
+    // interface at all → hard-fail, as before. Loopback-only is a distinct third
+    // outcome, NOT the null/throw case.
+    const bind = pickBindDecision(networkInterfaces());
+    if (bind.kind === "none") {
         emitSambaMarker("conf", "fail: no non-loopback IPv4 interface");
         throw new Error("samba-provision: no LAN interface with IPv4 — cannot bind smbd safely");
     }
+    const lanInterface = bind.kind === "lan" ? bind.lanInterface : null;
+    const bindPosture = bind.kind === "lan" ? `bind=lan iface=${bind.lanInterface}` : "bind=loopback-only";
     const SMB_CONF = "/etc/samba/smb.conf";
     let existing = "";
     if (existsSync(SMB_CONF)) {
@@ -3610,7 +3625,7 @@ function provisionSamba() {
         if (visudoCheck.status !== 0) {
             throw new Error(`visudo rejected ${SUDOERS}: ${(visudoCheck.stderr ?? "").trim()}`);
         }
-        emitSambaMarker("conf", `ok lan=${lanInterface} owner=${installOwner}`);
+        emitSambaMarker("conf", `ok ${bindPosture} owner=${installOwner}`);
     }
     catch (err) {
         const stderr = err instanceof Error ? err.message : String(err);
@@ -3624,9 +3639,11 @@ function provisionSamba() {
     // unbroken. Owner is recorded in the marker state so the install log shows
     // which Unix user the smbpasswd entry will target. Task 534.
     emitSambaMarker("user", `deferred reason=no-plaintext-pin-at-install owner=${installOwner} (set-pin route syncs)`);
-    // Step 4 — enable + start smbd and nmbd.
+    // Step 4 — enable + start smbd. nmbd (NetBIOS) is deliberately excluded —
+    // nothing mounts the share by NetBIOS name and it is a public DDoS-reflection
+    // vector (Task 755). The unit list is locked in samba-provision.ts.
     try {
-        shell("systemctl", ["enable", "--now", "smbd", "nmbd"], { sudo: true, timeout: 30_000 });
+        shell("systemctl", ["enable", "--now", ...SAMBA_ENABLE_UNITS], { sudo: true, timeout: 30_000 });
         emitSambaMarker("units", "ok");
     }
     catch (err) {

package/dist/port-resolution.js

@@ -187,16 +187,17 @@ WantedBy=default.target
 `;
 }
 // ---------------------------------------------------------------------------
-// Task 602 — `cloudflared.slice` unit. Every cloudflared-<brand>.scope
+// Task 602 — `cloudflared.slice` unit. Every cloudflared-<brand>.service
 // spawned by resume-tunnel.sh drops under this slice for one-glance cohort
-// observability (`systemctl --user status cloudflared.slice`).
+// observability (`systemctl --user status cloudflared.slice`). Task 757
+// changed the per-brand unit from a transient scope to a supervised service.
 //
 // Brand-agnostic: one slice across all co-resident brands, mirroring the
 // Task-250 claude-ptys.slice precedent.
 // ---------------------------------------------------------------------------
 export function buildCloudflaredSliceUnitFile() {
     return `[Unit]
-Description=Cloudflare tunnel scopes (Task 602)
+Description=Cloudflare tunnel connectors (Task 602)
 Documentation=https://github.com/rubytech/maxy-code/blob/main/.tasks/archive/602-cloudflared-tunnel-must-survive-brand-service-restart-via-systemd-scope.md
 Before=shutdown.target
 

package/dist/samba-provision.js

@@ -40,19 +40,31 @@ export function renderBrandStanza(input) {
     ].join("\n");
 }
 /**
- * Render the `[global]` section. `interfaces = lo <lan>` plus `bind interfaces
- * only = yes` is the LAN-only posture: smbd accepts connections on the LAN
- * interface and loopback, nothing else. Cloudflare tunnels carry HTTPS only,
- * so this is the structural guarantee that SMB never leaves the LAN even if
- * the firewall is misconfigured upstream.
+ * Render the `[global]` section. `bind interfaces only = yes` is always set; it
+ * is what makes `interfaces` an allow-list rather than a hint. The `interfaces`
+ * line has two shapes, keyed by `lanInterface`:
+ *
+ *   - `lanInterface = "<iface>"` → `interfaces = lo <iface>`. LAN-only posture:
+ *     smbd accepts connections on that interface and loopback, nothing else.
+ *     Used when the host has a private LAN interface (Pi).
+ *   - `lanInterface = null` → `interfaces = lo`. Loopback-only posture: smbd is
+ *     reachable solely from the box itself (SSH tunnel to `localhost:445`).
+ *     Used when the only non-loopback interface carries a public address
+ *     (Hetzner), so `bind interfaces only` would otherwise expose the share to
+ *     the public internet (Task 755).
+ *
+ * Cloudflare tunnels carry HTTPS only, so this is the structural guarantee that
+ * SMB never leaves the box (loopback-only) or the LAN (LAN-only) even if the
+ * firewall is misconfigured upstream.
  */
 export function renderGlobalSection(input) {
+    const interfaces = input.lanInterface === null ? `lo` : `lo ${input.lanInterface}`;
     return [
         `[global]`,
         `   workgroup = WORKGROUP`,
         `   server string = %h Samba`,
         `   server role = standalone server`,
-        `   interfaces = lo ${input.lanInterface}`,
+        `   interfaces = ${interfaces}`,
         `   bind interfaces only = yes`,
         `   log file = /var/log/samba/log.%m`,
         `   max log size = 1000`,
@@ -75,35 +87,70 @@ export function renderFullSmbConf(input) {
         renderBrandStanza({ brand: input.brand, sharePath: input.sharePath, installOwner: input.installOwner });
 }
 // ---------------------------------------------------------------------------
-// LAN interface detection
+// Interface classification and bind decision
 // ---------------------------------------------------------------------------
 /**
- * Pick the LAN interface to bind smbd to. Preference order: wlan0, eth0, then
- * the first non-loopback interface with a non-internal IPv4 address. Returns
- * null when no such interface exists — the caller treats that as a hard
- * failure (the Pi has no LAN connectivity; SMB has nothing to bind to).
+ * True when `address` is a private IPv4 address: RFC1918 (`10/8`, `172.16/12`,
+ * `192.168/16`), CGNAT (`100.64/10`), or link-local (`169.254/16`). These are
+ * the address spaces a Pi's LAN interface lives in. A routable public address
+ * (a Hetzner box's `eth0`) is not private — binding smbd to it would expose the
+ * share to the internet, which is the defect Task 755 fixes.
  *
- * Input is the shape returned by `os.networkInterfaces()` so the test can pass
- * realistic fixtures without spinning up real interfaces.
+ * Loopback (`127/8`) is not classified here because `os.networkInterfaces()`
+ * marks it `internal: true` and the caller excludes it before ever asking.
+ */
+export function isPrivateIPv4(address) {
+    const parts = address.split(".");
+    if (parts.length !== 4)
+        return false;
+    const octets = parts.map((p) => Number(p));
+    if (octets.some((n) => !Number.isInteger(n) || n < 0 || n > 255))
+        return false;
+    const [a, b] = octets;
+    if (a === 10)
+        return true; // 10.0.0.0/8
+    if (a === 172 && b >= 16 && b <= 31)
+        return true; // 172.16.0.0/12
+    if (a === 192 && b === 168)
+        return true; // 192.168.0.0/16
+    if (a === 100 && b >= 64 && b <= 127)
+        return true; // 100.64.0.0/10 (CGNAT)
+    if (a === 169 && b === 254)
+        return true; // 169.254.0.0/16 (link-local)
+    return false;
+}
+/**
+ * Decide how smbd should bind, given the shape returned by
+ * `os.networkInterfaces()` (so tests pass realistic fixtures without real
+ * interfaces). A private-addressed interface yields a LAN bind, in preference
+ * order wlan0, eth0, then the first other; this keeps the Pi path byte-
+ * identical to before. If non-loopback IPv4 interfaces exist but none is
+ * private, the host is public-only and the decision is loopback-only. If no
+ * non-loopback IPv4 interface exists, the decision is none.
  */
-export function pickLanInterface(ifaces) {
-    const hasIPv4 = (name) => {
+export function pickBindDecision(ifaces) {
+    const ipv4Addrs = (name) => {
         const addrs = ifaces[name];
         if (!addrs)
-            return false;
-        return addrs.some((a) => a.family === "IPv4" && !a.internal);
+            return [];
+        return addrs.filter((a) => a.family === "IPv4" && !a.internal).map((a) => a.address);
     };
-    if (hasIPv4("wlan0"))
-        return "wlan0";
-    if (hasIPv4("eth0"))
-        return "eth0";
+    const isPrivateIface = (name) => ipv4Addrs(name).some(isPrivateIPv4);
+    // LAN bind: a private-addressed interface, in the established preference order.
+    if (isPrivateIface("wlan0"))
+        return { kind: "lan", lanInterface: "wlan0" };
+    if (isPrivateIface("eth0"))
+        return { kind: "lan", lanInterface: "eth0" };
     for (const name of Object.keys(ifaces)) {
         if (name === "lo")
             continue;
-        if (hasIPv4(name))
-            return name;
+        if (isPrivateIface(name))
+            return { kind: "lan", lanInterface: name };
     }
-    return null;
+    // No private interface. If any non-loopback IPv4 interface exists at all, the
+    // host is public-only → loopback-only. Otherwise there is nothing to bind to.
+    const hasNonLoopbackIPv4 = Object.keys(ifaces).some((name) => name !== "lo" && ipv4Addrs(name).length > 0);
+    return hasNonLoopbackIPv4 ? { kind: "loopback-only" } : { kind: "none" };
 }
 // ---------------------------------------------------------------------------
 // smb.conf merge / remove
@@ -213,6 +260,16 @@ export function hasAnyBrandStanza(conf) {
  * intentionally skipped because a precondition wasn't met).
  */
 export const SAMBA_STEPS = ["apt", "conf", "user", "units"];
+/**
+ * The systemd units the install's `units` step runs `enable --now` against.
+ * `smbd` only — `nmbd` (NetBIOS name service) is never enabled: nothing mounts
+ * the share by NetBIOS name (mDNS / LAN-IP only), and on a public-facing host
+ * nmbd answers on `:137`/`:138` as a DDoS-reflection vector (BSI/CERT-Bund,
+ * Task 755). Locked here, in the tested pure layer, so the install wrapper
+ * cannot silently reintroduce nmbd. Uninstall still *disables* nmbd defensively
+ * to converge pre-fix boxes — a separate command, see uninstall.ts.
+ */
+export const SAMBA_ENABLE_UNITS = ["smbd"];
 export function formatSambaMarker(step, state) {
     return `[install-invariant] samba-provision-${step} ${state}`;
 }

package/dist/uninstall.js

@@ -181,24 +181,25 @@ function stopServices() {
     catch {
         console.log(`  ${neo4jService} not running`);
     }
-    // Stop the cloudflared scope for this brand. The scope unit name mirrors
-    // what resume-tunnel.sh derives: strip leading dot from configDir.
-    // BRAND.configDir is ".maxy-code"; strip the dot → "maxy-code".
+    // Stop the cloudflared service for this brand (Task 757 — the connector now
+    // runs as a supervised cloudflared-<brand>.service, not a transient scope).
+    // The unit name mirrors what resume-tunnel.sh derives: strip leading dot from
+    // configDir. BRAND.configDir is ".maxy-code"; strip the dot → "maxy-code".
     // --no-block: uninstall does not wait for graceful shutdown of the tunnel.
-    // Exit 5 (no such unit) = scope absent = success.
+    // Exit 5 (no such unit) = service absent = success.
     const brand = BRAND.configDir.replace(/^\./, "");
-    const scopeUnit = `cloudflared-${brand}.scope`;
-    const stopResult = spawnSync("systemctl", ["--user", "stop", "--no-block", scopeUnit], { stdio: "pipe" });
+    const serviceUnit = `cloudflared-${brand}.service`;
+    const stopResult = spawnSync("systemctl", ["--user", "stop", "--no-block", serviceUnit], { stdio: "pipe" });
     if (stopResult.status === 0) {
-        console.log(`  Stopped ${scopeUnit}`);
+        console.log(`  Stopped ${serviceUnit}`);
     }
     else if (stopResult.status === 5) {
-        // exit 5 = unit not found — scope already absent, which is expected
-        console.log(`  ${scopeUnit} not running (scope absent)`);
+        // exit 5 = unit not found — service already absent, which is expected
+        console.log(`  ${serviceUnit} not running (service absent)`);
     }
     else {
         // Any other non-zero exit means systemctl itself failed (e.g. DBus unavailable)
-        console.log(`  systemctl stop ${scopeUnit} exited ${stopResult.status} — scope may still be running`);
+        console.log(`  systemctl stop ${serviceUnit} exited ${stopResult.status} — service may still be running`);
     }
     // Brand isolation: the VNC stack and Ollama daemon are
     // device-wide singletons. Killing them during uninstall would interrupt
@@ -754,7 +755,11 @@ function removeSamba() {
         console.log(`  Leaving smbd/nmbd + samba package in place — ${reason}`);
         return;
     }
-    // No brand stanza, no peer brand — full device-wide teardown.
+    // No brand stanza, no peer brand — full device-wide teardown. nmbd is kept
+    // in the disable list even though install (Task 755) no longer enables it:
+    // disabling an absent unit is a no-op, and this defensively converges a box
+    // that was provisioned by a pre-fix installer (where nmbd was enabled) to the
+    // intended nmbd-off end state. Do not "simplify" nmbd out of this list.
     try {
         spawnSync("sudo", ["systemctl", "disable", "--now", "smbd", "nmbd"], { stdio: "pipe", timeout: 30_000 });
         console.log("  Stopped + disabled smbd, nmbd");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-maxy-code",
-  "version": "0.1.286",
+  "version": "0.1.288",
   "description": "Install Maxy — AI for Productive People",
   "bin": {
     "create-maxy-code": "./dist/index.js"

package/payload/platform/plugins/admin/PLUGIN.md

@@ -147,7 +147,7 @@ Tools are available via the `admin` MCP server.
 - `hooks/mcp-tool-missing.sh` — **PostToolUse hook on `mcp__.*` (Task 502, directive 3).** Defence-in-depth for the `No such tool available: mcp__…` failure class that the Task 502 name-binding is built to eliminate. Fires on any MCP tool call; no-op unless the `tool_response` carries `No such tool available` AND the qualified name resolves to a maxy plugin (read from the generated `hooks/lib/maxy-mcp-plugins.txt`). On a maxy match it logs one deterministic `[mcp-tool-missing] server=<server> tool=<tool>` line and exits 2 with a fixed envelope on stderr, so the agent relays a named server-unavailable failure instead of narrating "warming up" or blind-retrying. A missing non-maxy bridge tool (Playwright etc., upstream-owned) passes through (exit 0). The maxy-plugin list is regenerated and gate-diffed by `platform/scripts/check-canonical-tool-names.mjs`.
 - `hooks/post-tool-use-agent.sh` — **PostToolUse hook on `Agent` (Task 560).** Drains any subagent hook-decision buffers under `~/.maxy-code/logs/hook-decisions/` modified since this parent's previous PostToolUse-Agent fire (cursor file keyed by parent session id), prints one `[hook-propagate]` line per record to stdout — Claude Code attaches the stdout as a `hook_success` attachment on the parent JSONL, making the records grep-queryable from the parent session alone (Task 559 motivating case). Rotates consumed buffers to `consumed/`. Emits one `[hook-propagate-census] parentSession=<…> subagentHooksObserved=<N> attachmentsEmitted=<M>` line per fire to stdout and server.log; `N != M` is the propagation regression signal. The companion emitter library `hooks/lib/hook-emit.sh` is sourced by `post-tool-use-agent.sh` and any other hook that records a block decision (4 KB stderr truncation, `truncated=true` set on the record).
 - `hooks/admin-authoring-observer.sh` — **PostToolUse hook on Write and Edit (Task 486).** Observation only — never blocks; exits 0 on every path. Fires when the admin agent (not a specialist subagent — gated by `MAXY_SPECIALIST` env) writes or edits a file under `<accountDir>/output/`. Walks the session transcript from the latest real-user turn forward to detect any prior `Task` `tool_use` whose `subagent_type` starts with `specialists:`. Emits one stderr line `[admin-authoring] inline-write path=<rel> priorSpecialistSpawnInTurn=<true|false|unknown>`. A `false` value on a long-form prose file is the regression signal Task 486 was designed to make visible — the BioSymm proposal session (admin authored a customer-facing proposal inline despite content-producer being installed) is the failure mode this surfaces mechanically. Mechanical enforcement (refuse the write, force a re-spawn) is deferred per the task spec.
-- `hooks/prompt-optimiser-directive.sh` — **UserPromptSubmit hook (Task 698).** Injects the standing prompt-optimiser restatement directive plus the per-turn three-tier routing ladder as `additionalContext`: **(1)** delegate to the specialist that owns the deliverable via the Agent tool — the brief states the outcome plus binding constraints, never lines/anchors/literal text; **(2)** only if none fits, load an admin-usable skill with `skill-load`; **(3)** only if neither fits, author inline — freestyle is the named last resort. Re-emits the full agent roster (`agents/admin/AGENTS.md`) and the full admin-usable skills list (`agents/admin/ADMIN-SKILLS.md`) every turn by reading the two generated files from the account dir (the hook fires with the account dir as cwd); it never walks the plugins tree per turn. Fail-open is **visible**: a missing list logs `[prompt-optimiser] missing=<AGENTS.md\|ADMIN-SKILLS.md> emitting-partial` to stderr and the ladder still injects. The trivial-turn skip (one-word confirmation, slash-command, direct continuation) is unchanged. **Staleness:** `ADMIN-SKILLS.md` is regenerated only by `setup-account.sh`; a plugin add/remove since the last setup leaves the list stale — compare `ADMIN-SKILLS.md` mtime against the newest `SKILL.md` mtime and re-run setup to refresh. The list generator is `platform/scripts/lib/admin-skills-bootstrap.sh`; it logs `[admin-skills] scanned=<N> admin-usable=<M> no-declaration=<K>` (failure signature: `admin-usable=0` while `scanned>0`, or any `missing-declaration` line). **Task 719:** the directive now carries a standing CAPABILITY-QUESTIONS-ARE-OWNED-WORK clause (how-to / "do you have instructions for X" / config questions about platform features are answered from the owning specialist or plugin tool/reference, never from training memory), and the hook appends a durable `<ts> [prompt-optimiser-directive] injected len=<n> session=<id>` breadcrumb to `$LOG_DIR/prompt-optimiser-directive.log` so per-turn injection is greppable, not stderr-only.
+- `hooks/prompt-optimiser-directive.sh` — **UserPromptSubmit hook (Task 698).** Injects the standing prompt-optimiser restatement directive plus the per-turn three-tier routing ladder as `additionalContext`: **(1)** delegate to the specialist that owns the deliverable via the Agent tool — the brief states the outcome plus binding constraints, never lines/anchors/literal text; **(2)** only if none fits, load an admin-usable skill with `skill-load`; **(3)** only if neither fits, author inline — freestyle is the named last resort. Re-emits the full agent roster (`agents/admin/AGENTS.md`) and the full admin-usable skills list (`agents/admin/ADMIN-SKILLS.md`) every turn by reading the two generated files from the account dir (the hook fires with the account dir as cwd); it never walks the plugins tree per turn. Fail-open is **visible**: a missing list logs `[prompt-optimiser] missing=<AGENTS.md\|ADMIN-SKILLS.md> emitting-partial` to stderr and the ladder still injects. The trivial-turn skip (one-word confirmation, slash-command, direct continuation) is unchanged. **Staleness:** `ADMIN-SKILLS.md` is regenerated only by `setup-account.sh`; a plugin add/remove since the last setup leaves the list stale — compare `ADMIN-SKILLS.md` mtime against the newest `SKILL.md` mtime and re-run setup to refresh. The list generator is `platform/scripts/lib/admin-skills-bootstrap.sh`; it logs `[admin-skills] scanned=<N> admin-usable=<M> no-declaration=<K>` (failure signature: `admin-usable=0` while `scanned>0`, or any `missing-declaration` line). **Task 719:** the directive now carries a standing CAPABILITY-QUESTIONS-ARE-OWNED-WORK clause (how-to / "do you have instructions for X" / config questions about platform features are answered from the owning specialist or plugin tool/reference, never from training memory), and the hook appends a durable `<ts> [prompt-optimiser-directive] injected len=<n> session=<id>` breadcrumb to `$LOG_DIR/prompt-optimiser-directive.log` so per-turn injection is greppable, not stderr-only. **Task 753:** the directive is **suppressed on native channel turns** — when the parsed `.prompt` starts with the `<channel source=` event marker, the hook logs `[prompt-optimiser-directive] skipped reason=channel-turn session=<id>` to stderr and exits without injecting, because the channel service already reframes the inbound into a select-and-dispatch turn (`composeAdminContent`, see `.docs/whatsapp-inbound-lifeline.md`). Marker-matched at start-of-prompt only, so an admin/Terminal prompt that merely mentions "channel" still gets the directive; fail-open injects if the prompt cannot be parsed.
 - `hooks/prompt-optimiser-compliance.sh` — **Stop hook (Task 719).** After each admin turn, reads the just-finished turn from `transcript_path` and appends `<ts> [prompt-optimiser-compliance] directive-fired no-route-taken session=<id8> prompt="<clip>"` to `$LOG_DIR/prompt-optimiser-directive.log` (and stderr) when the routing directive fired, the prompt was non-trivial (not a slash-command, not a one-word confirmation), and the turn took **no route** — no `Agent` dispatch, no `Skill` load, no `ToolSearch`, no `mcp__*` tool call. This is the standing compliance signal that surfaces the session-`da0b12d4` failure class (agent answers a capability question from memory) as a visible event instead of a silent stale answer. Directive-fired is detected by the marker `PROMPT-OPTIMISER DIRECTIVE` in the turn slice, so it is robust to the CC-version difference in how `UserPromptSubmit` `additionalContext` is recorded (`attachment`/`hook_success` vs `hook_additional_context`). **Known limitation:** "direct continuation of the prior turn" is not detectable from the transcript, so a continuation turn that legitimately needs no route can be flagged; treat the log as a review signal, not a gate. **Fail-open:** no python3, no `transcript_path`, or an unreadable transcript → exit 0, no output. Lives in the same log as the directive breadcrumb, so a single `grep` interleaves "fired" and "no-route" into one per-session timeline; cross-check via `platform/scripts/logs-read.sh <sessionKey>`. This is a lightweight transcript read, not a per-turn spawn (contrast the Task-626 turn recorder below).
 - **Turn recorder — removed entirely (Task 626).** The `turn-completed-graph-write.sh` Stop hook, the `/api/admin/claude-sessions` loopback bypass it relied on, the `[turn-recorder]` emitters, the envelope walker, and the recorder-auto-archive subscriber are deleted. It had been dormant since Task 214 (never re-registered in settings.json); the admin now writes to the graph by delegating to `database-operator` via the Task tool inside the live session, and the on-demand `/insight` pass (`skills/insight/SKILL.md`, a registered admin skill — Task 641) is the per-session review. There is no per-turn spawn.
 

package/payload/platform/plugins/admin/hooks/__tests__/prompt-optimiser-compliance.test.sh

@@ -41,6 +41,10 @@ ASSISTANT_AGENT='{"type":"assistant","message":{"role":"assistant","content":[{"
 ASSISTANT_SKILL='{"type":"assistant","message":{"role":"assistant","content":[{"type":"tool_use","name":"Skill","input":{}}]}}'
 ASSISTANT_MCP='{"type":"assistant","message":{"role":"assistant","content":[{"type":"tool_use","name":"mcp__plugin_email__email-provider-info","input":{}}]}}'
 ASSISTANT_TOOLSEARCH='{"type":"assistant","message":{"role":"assistant","content":[{"type":"tool_use","name":"ToolSearch","input":{}}]}}'
+ASSISTANT_REPLY='{"type":"assistant","message":{"role":"assistant","content":[{"type":"tool_use","name":"mcp__whatsapp-channel__reply","input":{}}]}}'
+ASSISTANT_REPLYDOC='{"type":"assistant","message":{"role":"assistant","content":[{"type":"tool_use","name":"mcp__whatsapp-channel__reply-document","input":{}}]}}'
+ASSISTANT_SKILLLOAD='{"type":"assistant","message":{"role":"assistant","content":[{"type":"tool_use","name":"mcp__admin__skill-load","input":{}}]}}'
+ASSISTANT_TASK='{"type":"assistant","message":{"role":"assistant","content":[{"type":"tool_use","name":"Task","input":{}}]}}'
 
 assert_flagged() {
   local name="$1" t="$2" out
@@ -72,15 +76,37 @@ assert_flagged "attachment-shape directive + no route -> flagged" \
 assert_flagged "pi-shape directive + no route -> flagged" \
   "$(mk_transcript "$USER_PROMPT" "$DIRECTIVE_PI" "$ASSISTANT_TEXT")"
 
-# 3–6. Each route surface suppresses the flag.
+# 3–4. Genuine routes suppress the flag.
 assert_not_flagged "Agent dispatch -> not flagged" \
   "$(mk_transcript "$USER_PROMPT" "$DIRECTIVE_ATTACH" "$ASSISTANT_AGENT")"
 assert_not_flagged "Skill load -> not flagged" \
   "$(mk_transcript "$USER_PROMPT" "$DIRECTIVE_ATTACH" "$ASSISTANT_SKILL")"
-assert_not_flagged "mcp__ tool -> not flagged" \
+
+# 5. A non-owning direct mcp__ call is NOT a route -> flagged (kills the
+#    "any direct admin MCP call satisfies it" defect; Task 747).
+assert_flagged "non-route mcp__ tool only -> flagged" \
   "$(mk_transcript "$USER_PROMPT" "$DIRECTIVE_ATTACH" "$ASSISTANT_MCP")"
-assert_not_flagged "ToolSearch -> not flagged" \
+# 6. ToolSearch is a schema load, not a route -> flagged (Task 747).
+assert_flagged "ToolSearch only -> flagged" \
   "$(mk_transcript "$USER_PROMPT" "$DIRECTIVE_ATTACH" "$ASSISTANT_TOOLSEARCH")"
+# 6a. Channel transport reply alone is mandatory transport, not a route -> flagged.
+assert_flagged "channel reply transport only -> flagged" \
+  "$(mk_transcript "$USER_PROMPT" "$DIRECTIVE_ATTACH" "$ASSISTANT_REPLY")"
+# 6b. reply-document transport alone -> flagged.
+assert_flagged "channel reply-document transport only -> flagged" \
+  "$(mk_transcript "$USER_PROMPT" "$DIRECTIVE_ATTACH" "$ASSISTANT_REPLYDOC")"
+# 6c. The e48c2a5e shape: reply + ToolSearch only -> flagged.
+assert_flagged "reply + ToolSearch only (e48c2a5e shape) -> flagged" \
+  "$(mk_transcript "$USER_PROMPT" "$DIRECTIVE_ATTACH" "$ASSISTANT_REPLY" "$ASSISTANT_TOOLSEARCH")"
+# 6d. Task dispatch is a route -> not flagged.
+assert_not_flagged "Task dispatch -> not flagged" \
+  "$(mk_transcript "$USER_PROMPT" "$DIRECTIVE_ATTACH" "$ASSISTANT_TASK")"
+# 6e. The mcp__admin__skill-load tool is a route -> not flagged.
+assert_not_flagged "skill-load MCP tool -> not flagged" \
+  "$(mk_transcript "$USER_PROMPT" "$DIRECTIVE_ATTACH" "$ASSISTANT_SKILLLOAD")"
+# 6f. reply transport then a genuine Agent dispatch -> not flagged (route present).
+assert_not_flagged "reply then Agent dispatch -> not flagged" \
+  "$(mk_transcript "$USER_PROMPT" "$DIRECTIVE_ATTACH" "$ASSISTANT_REPLY" "$ASSISTANT_AGENT")"
 
 # 7. No directive in the slice -> not flagged.
 assert_not_flagged "no directive -> not flagged" \
@@ -149,6 +175,29 @@ else
 fi
 rm -rf "$LD" "$t13"
 
+# 14. The emitted flag carries the tools= CSV of tool names seen in the slice,
+# in order (Task 747 observability). A future false-negative shows which tool was
+# (mis)counted.
+t14=$(mk_transcript "$USER_PROMPT" "$DIRECTIVE_ATTACH" "$ASSISTANT_REPLY" "$ASSISTANT_TOOLSEARCH")
+out14=$(run_hook "$t14")
+if printf '%s' "$out14" | grep -q 'tools=mcp__whatsapp-channel__reply,ToolSearch'; then
+  echo "PASS: tools= CSV lists the slice's tool names in order"; PASS=$((PASS+1))
+else
+  echo "FAIL: tools= CSV wrong (got: $out14)" >&2; FAIL=$((FAIL+1))
+fi
+rm -f "$t14"
+
+# 15. A no-mcp freestyle turn (the 45617005 shape) still flags, with an empty
+# tools= field (no tool calls in the slice).
+t15=$(mk_transcript "$USER_PROMPT" "$DIRECTIVE_ATTACH" "$ASSISTANT_TEXT")
+out15=$(run_hook "$t15")
+if printf '%s' "$out15" | grep -q "no-route-taken" && printf '%s' "$out15" | grep -q 'tools= prompt='; then
+  echo "PASS: no-tool freestyle turn flags with empty tools="; PASS=$((PASS+1))
+else
+  echo "FAIL: no-tool freestyle tools= wrong (got: $out15)" >&2; FAIL=$((FAIL+1))
+fi
+rm -f "$t15"
+
 echo "----"
 echo "PASS=$PASS FAIL=$FAIL"
 [[ "$FAIL" -eq 0 ]]