@rubytech/create-maxy-code 0.1.286 → 0.1.287

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.
@@ -3512,7 +3512,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 +3563,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 +3617,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 +3631,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/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

@@ -754,7 +754,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.287",
   "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 ]]

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

@@ -131,6 +131,61 @@ else
 fi
 rm -rf "$LD"
 
+# Case 7 — Task 746: full directive persisted per turn. With LOG_DIR + a
+# session id, the hook writes a content file whose bytes equal the emitted
+# additionalContext, and the breadcrumb carries file= pointing at it plus a
+# sha256 matching that file's bytes.
+P746=$(mktemp -d)
+out746=$(printf '%s' '{"prompt":"x","session_id":"sess-746-a"}' | LOG_DIR="$P746" bash "$HOOK" 2>/dev/null)
+printf '%s' "$out746" | python3 -c 'import json,sys; sys.stdout.write(json.load(sys.stdin)["hookSpecificOutput"]["additionalContext"])' > "$P746/expected.txt" 2>/dev/null
+crumb="$P746/prompt-optimiser-directive.log"
+dfile=$(grep -o 'file=[^ ]*' "$crumb" 2>/dev/null | head -1 | cut -d= -f2-)
+slog=$(grep -o 'sha256=[0-9a-f]*' "$crumb" 2>/dev/null | head -1 | cut -d= -f2)
+sfile=$(python3 -c 'import hashlib,sys; print(hashlib.sha256(open(sys.argv[1],"rb").read()).hexdigest())' "$dfile" 2>/dev/null)
+if [[ -f "$dfile" ]] && cmp -s "$dfile" "$P746/expected.txt" \
+   && [[ -n "$slog" && "$slog" == "$sfile" ]] \
+   && [[ "$dfile" == "$P746/prompt-optimiser-directives/sess-746-a/"*.txt ]]; then
+  echo "PASS: full directive persisted; breadcrumb file=/sha256 match content"; PASS=$((PASS+1))
+else
+  echo "FAIL: directive content store wrong (file=$dfile slog=$slog sfile=$sfile)" >&2; FAIL=$((FAIL+1))
+fi
+
+# Case 8 — two injections in one session produce two distinct content files
+# (one file per injection, so the audit's injected==stored invariant holds).
+printf '%s' '{"prompt":"y","session_id":"sess-746-b"}' | LOG_DIR="$P746" bash "$HOOK" >/dev/null 2>&1
+sleep 1
+printf '%s' '{"prompt":"z","session_id":"sess-746-b"}' | LOG_DIR="$P746" bash "$HOOK" >/dev/null 2>&1
+nfiles=$(ls "$P746/prompt-optimiser-directives/sess-746-b/"*.txt 2>/dev/null | wc -l | tr -d ' ')
+if [[ "$nfiles" -eq 2 ]]; then
+  echo "PASS: two injections -> two distinct content files"; PASS=$((PASS+1))
+else
+  echo "FAIL: expected 2 content files for sess-746-b, got $nfiles" >&2; FAIL=$((FAIL+1))
+fi
+rm -rf "$P746"
+
+# Case 9 — Task 753: a native channel turn (the prompt is a `<channel source=`
+# event) suppresses the directive — the event-text reframe replaces it there.
+# Exit 0, EMPTY stdout (nothing injected), and a visible stderr breadcrumb.
+chan_in='{"hook_event_name":"UserPromptSubmit","prompt":"<channel source=\"whatsapp\" sender_id=\"x\">\nprice the Willow House job\n</channel>","session_id":"chan-1"}'
+chan_out=$(printf '%s' "$chan_in" | bash "$HOOK" 2>/dev/null); chan_exit=$?
+chan_err=$(printf '%s' "$chan_in" | bash "$HOOK" 2>&1 >/dev/null)
+if [[ "$chan_exit" -eq 0 && -z "$chan_out" ]] \
+   && printf '%s' "$chan_err" | grep -q "skipped reason=channel-turn"; then
+  echo "PASS: channel turn -> directive suppressed (exit 0, empty stdout, breadcrumb)"; PASS=$((PASS+1))
+else
+  echo "FAIL: channel-turn suppression wrong (exit=$chan_exit stdout=$chan_out err=$chan_err)" >&2; FAIL=$((FAIL+1))
+fi
+
+# Case 10 — Task 753: a normal admin turn that merely MENTIONS the word channel
+# is NOT suppressed — only the `<channel source=` event marker suppresses, so a
+# Terminal/admin prompt still gets the directive.
+norm_out=$(printf '%s' '{"prompt":"please open a support channel for acme"}' | bash "$HOOK" 2>/dev/null); norm_exit=$?
+if [[ "$norm_exit" -eq 0 ]] && printf '%s' "$norm_out" | grep -q "hookSpecificOutput"; then
+  echo "PASS: non-channel prompt mentioning 'channel' still gets the directive"; PASS=$((PASS+1))
+else
+  echo "FAIL: false-suppression on a normal prompt (exit=$norm_exit stdout=$norm_out)" >&2; FAIL=$((FAIL+1))
+fi
+
 echo "----"
 echo "PASS=$PASS FAIL=$FAIL"
 [[ "$FAIL" -eq 0 ]]

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

@@ -12,14 +12,20 @@
 #                     UserPromptSubmit additionalContext is recorded: a
 #                     type:"attachment"/hook_success on 2.1.x, a
 #                     type:"hook_additional_context" on the Pi).
-#   route taken     = the turn contains a tool_use named Agent, Skill, ToolSearch,
-#                     or matching mcp__*.
+#   route taken     = the turn contains a tool_use that is a genuine route:
+#                     Agent/Task dispatch, native Skill, or a *__skill-load MCP
+#                     tool. ToolSearch (a schema load) and the channel transport
+#                     reply tools (mcp__*-channel__reply/-document) are NOT routes
+#                     — counting them was the Task 747 bug that blinded the
+#                     detector on every channel turn (the reply is mandatory).
 #   trivial         = the prompt is a slash-command or a one-word confirmation.
 # "Direct continuation" is NOT detectable from the transcript and is a stated
 # known limitation, not guessed.
 #
 # Emits, only on (directive fired AND not trivial AND no route):
-#   <ts> [prompt-optimiser-compliance] directive-fired no-route-taken session=<id8> prompt="<clip>"
+#   <ts> [prompt-optimiser-compliance] directive-fired no-route-taken session=<id8> tools=<csv> prompt="<clip>"
+#   tools=<csv> is the comma-joined tool names seen in the slice (empty on a
+#   no-tool freestyle turn), so a future false-negative shows what was (mis)counted.
 # to $LOG_DIR/prompt-optimiser-directive.log (same log as the fired breadcrumb,
 # so the two interleave into one greppable timeline) and to stderr.
 #
@@ -138,12 +144,20 @@ is_one_word = len(tokens) <= 1
 marker = "PROMPT-OPTIMISER DIRECTIVE"
 directive_fired = any(marker in json.dumps(r, ensure_ascii=False) for r in slice_rows)
 
-# Route taken = an assistant tool_use with a routing tool name.
-ROUTE_TOOLS = ("Agent", "Skill", "ToolSearch")
+# Route taken = an assistant tool_use that is a genuine route: specialist
+# dispatch (Agent/Task) or skill load (native Skill, or the *__skill-load MCP
+# tool under either admin namespace). ToolSearch is a schema load, and the channel
+# transport reply tools (mcp__*-channel__reply / reply-document) are mandatory
+# transport, not routes — neither counts. Every tool name in the slice is
+# collected for the tools= breadcrumb so a future false-negative shows what was
+# (mis)counted.
+ROUTE_TOOLS = ("Agent", "Task", "Skill")
 def is_route(name):
-    return name in ROUTE_TOOLS or (isinstance(name, str) and name.startswith("mcp__"))
+    if not isinstance(name, str):
+        return False
+    return name in ROUTE_TOOLS or name.endswith("__skill-load")
 
-route_taken = False
+tool_names = []
 for r in slice_rows:
     if not isinstance(r, dict) or r.get("type") != "assistant":
         continue
@@ -151,17 +165,19 @@ for r in slice_rows:
     content = msg.get("content")
     if isinstance(content, list):
         for b in content:
-            if isinstance(b, dict) and b.get("type") == "tool_use" and is_route(b.get("name")):
-                route_taken = True
-                break
-    if route_taken:
-        break
+            if isinstance(b, dict) and b.get("type") == "tool_use":
+                nm = b.get("name")
+                if isinstance(nm, str):
+                    tool_names.append(nm)
+
+route_taken = any(is_route(n) for n in tool_names)
 
 if directive_fired and not is_slash and not is_one_word and not route_taken:
     clip = prompt_text.replace("\n", " ")[:80]
     ts = datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
     sid8 = session[:8] if isinstance(session, str) else "?"
-    print("%s [prompt-optimiser-compliance] directive-fired no-route-taken session=%s prompt=\"%s\"" % (ts, sid8, clip))
+    tools_csv = ",".join(tool_names)
+    print("%s [prompt-optimiser-compliance] directive-fired no-route-taken session=%s tools=%s prompt=\"%s\"" % (ts, sid8, tools_csv, clip))
 ' 2>/dev/null) || exit 0
 
 [ -n "$RESULT" ] || exit 0