@rubytech/create-maxy-code 0.1.573 → 0.1.574

package/payload/platform/plugins/admin/hooks/__tests__/specialist-dispatch-gate.test.sh

@@ -0,0 +1,158 @@
+#!/usr/bin/env bash
+# Regression test for specialist-dispatch-gate.sh.
+#
+# An account's own specialists own their tools: the admin does not do their work
+# by hand. The gate refuses a main-conversation call to a tool one of the
+# account's authored cards declares, and names the specialist to dispatch.
+#
+# Two narrowings are load-bearing and both are asserted here. Only cards the
+# ACCOUNT authored count — provisioning copies every shipped template in, and one
+# of them declares roughly 130 tools including the whole email surface, so
+# reading every card would refuse the admin nearly its entire seat. And native
+# tools are never gated, because every card declares some of them.
+#
+# Caller identity is `agent_type`, which Claude Code sets when a hook fires
+# inside a subagent and leaves empty in the main conversation.
+#
+# Covers:
+#   A. main conversation, authored tool           → BLOCKED, names the specialist
+#   B. same call inside a subagent                → ALLOWED (never filters a subagent)
+#   C. a native tool the card also declares       → ALLOWED
+#   D. a tool only a shipped template declares    → ALLOWED
+#   E. a tool only a premium bundle declares      → ALLOWED
+#   F. an account with no authored cards          → ALLOWED
+#   G. empty stdin                                → ALLOWED
+#   H. unparseable envelope                       → ALLOWED
+#   I. an unreadable specialists dir              → ALLOWED, op=degraded on stderr
+#   J. a card under the ACCOUNT's own plugin root → BLOCKED (still the account's own)
+#   K. the refuse line carries the account and the tool
+#   L. the native set matches CC_NATIVE_TOOLS in the session manager
+
+set -uo pipefail
+HOOKS_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+GATE="$HOOKS_DIR/specialist-dispatch-gate.sh"
+DRIFT_SOURCE="$(cd "$HOOKS_DIR/../../../services/claude-session-manager/src" && pwd)/specialist-drift.ts"
+
+PASS=0
+FAIL=0
+ok()  { PASS=$((PASS + 1)); echo "  ok   $1"; }
+bad() { FAIL=$((FAIL + 1)); echo "  FAIL $1"; }
+
+ROOT="$(mktemp -d)"
+trap 'chmod -R u+rwX "$ROOT" 2>/dev/null; rm -rf "$ROOT"' EXIT
+
+ACCT="$ROOT/2078cb54aaaa"
+PLATFORM="$ROOT/platform"
+PREMIUM="$ROOT/premium-plugins"
+mkdir -p "$ACCT/specialists/agents" \
+         "$PLATFORM/templates/specialists/agents" \
+         "$PLATFORM/plugins" \
+         "$PREMIUM/sitedesk/agents"
+
+card() { # dir file name tools
+  mkdir -p "$1"
+  printf -- '---\nname: %s\ndescription: "d"\ntools: %s\n---\nbody\n' "$3" "$4" > "$1/$2"
+}
+
+# The account's own clerk: no copy in any shipped root.
+card "$ACCT/specialists/agents" "glsmith--email-clerk.md" "email-clerk" \
+     "Read, Bash, mcp__plugin_email_email__email-draft"
+# A shipped template, copied into the account by provisioning.
+card "$ACCT/specialists/agents" "personal-assistant.md" "personal-assistant" \
+     "mcp__plugin_whatsapp_whatsapp__whatsapp-send-admin"
+card "$PLATFORM/templates/specialists/agents" "personal-assistant.md" "personal-assistant" \
+     "mcp__plugin_whatsapp_whatsapp__whatsapp-send-admin"
+# A premium bundle card, also copied in.
+card "$ACCT/specialists/agents" "sitedesk--quoter.md" "quoter" \
+     "mcp__plugin_sitedesk-job_sitedesk-job__quote-render"
+card "$PREMIUM/sitedesk/agents" "sitedesk--quoter.md" "quoter" \
+     "mcp__plugin_sitedesk-job_sitedesk-job__quote-render"
+# An authored card whose durable copy lives under the ACCOUNT's own plugin root.
+card "$ACCT/specialists/agents" "glsmith--order-clerk.md" "order-clerk" \
+     "mcp__plugin_work_work__work-create"
+card "$ACCT/plugins/glsmith/agents" "glsmith--order-clerk.md" "order-clerk" \
+     "mcp__plugin_work_work__work-create"
+
+envelope() { printf '{"tool_name":"%s","agent_type":%s,"tool_input":{}}' "$1" "$2"; }
+
+# fire <cwd> <json> — sets RC and ERR
+fire() {
+  ERR="$(cd "$1" && printf '%s' "$2" | PLATFORM_ROOT="$PLATFORM" bash "$GATE" 2>&1 >/dev/null)"
+  RC=$?
+}
+
+# A
+fire "$ACCT" "$(envelope mcp__plugin_email_email__email-draft '""')"
+if [ "$RC" = 2 ] && printf '%s' "$ERR" | grep -q 'email-clerk'; then
+  ok "A blocks the main conversation and names the specialist"
+else bad "A rc=$RC err=$ERR"; fi
+
+# B
+fire "$ACCT" "$(envelope mcp__plugin_email_email__email-draft '"specialists:email-clerk"')"
+if [ "$RC" = 0 ]; then ok "B allows the same call inside a subagent"; else bad "B rc=$RC err=$ERR"; fi
+
+# C
+fire "$ACCT" "$(envelope Bash '""')"
+if [ "$RC" = 0 ]; then ok "C allows a native tool the card declares"; else bad "C rc=$RC err=$ERR"; fi
+
+# D
+fire "$ACCT" "$(envelope mcp__plugin_whatsapp_whatsapp__whatsapp-send-admin '""')"
+if [ "$RC" = 0 ]; then ok "D allows a tool only a shipped template declares"; else bad "D rc=$RC err=$ERR"; fi
+
+# E
+fire "$ACCT" "$(envelope mcp__plugin_sitedesk-job_sitedesk-job__quote-render '""')"
+if [ "$RC" = 0 ]; then ok "E allows a tool only a premium bundle declares"; else bad "E rc=$RC err=$ERR"; fi
+
+# F
+EMPTY="$ROOT/empty"
+mkdir -p "$EMPTY/specialists/agents"
+fire "$EMPTY" "$(envelope mcp__plugin_email_email__email-draft '""')"
+if [ "$RC" = 0 ]; then ok "F allows on an account with no authored cards"; else bad "F rc=$RC err=$ERR"; fi
+
+# G
+fire "$ACCT" ""
+if [ "$RC" = 0 ]; then ok "G allows on empty stdin"; else bad "G rc=$RC err=$ERR"; fi
+
+# H
+fire "$ACCT" '{not json'
+if [ "$RC" = 0 ]; then ok "H allows on an unparseable envelope"; else bad "H rc=$RC err=$ERR"; fi
+
+# I — failing open is fine; failing open SILENTLY is the fault.
+BROKEN="$ROOT/brokenacct"
+mkdir -p "$BROKEN/specialists/agents"
+chmod 000 "$BROKEN/specialists/agents"
+fire "$BROKEN" "$(envelope mcp__plugin_email_email__email-draft '""')"
+chmod 755 "$BROKEN/specialists/agents"
+if [ "$RC" = 0 ] && printf '%s' "$ERR" | grep -q 'op=degraded'; then
+  ok "I fails open and says so"
+else bad "I rc=$RC err=$ERR"; fi
+
+# J
+fire "$ACCT" "$(envelope mcp__plugin_work_work__work-create '""')"
+if [ "$RC" = 2 ] && printf '%s' "$ERR" | grep -q 'order-clerk'; then
+  ok "J blocks a card whose durable copy is under the account plugin root"
+else bad "J rc=$RC err=$ERR"; fi
+
+# K
+fire "$ACCT" "$(envelope mcp__plugin_email_email__email-draft '""')"
+if printf '%s' "$ERR" | grep -q 'op=refuse account=2078cb54 tool=mcp__plugin_email_email__email-draft specialist=email-clerk'; then
+  ok "K the refuse line carries the account, the tool and the specialist"
+else bad "K err=$ERR"; fi
+
+# L — the hook cannot import the manager's TypeScript, so it mirrors
+# CC_NATIVE_TOOLS as a python literal. A mirror that drifts silently un-gates or
+# over-gates, so the two sets are compared rather than trusted.
+TS_SET="$(sed -n '/export const CC_NATIVE_TOOLS/,/^\])/p' "$DRIFT_SOURCE" \
+  | grep -oE "'[A-Za-z]+'" | tr -d "'" | sort -u)"
+SH_SET="$(sed -n '/^NATIVE = {/,/^}/p' "$GATE" \
+  | grep -oE '"[A-Za-z]+"' | tr -d '"' | sort -u)"
+if [ "$TS_SET" = "$SH_SET" ]; then
+  ok "L the native set matches CC_NATIVE_TOOLS"
+else
+  bad "L native sets differ:"
+  diff <(printf '%s\n' "$TS_SET") <(printf '%s\n' "$SH_SET") | sed 's/^/       /'
+fi
+
+echo "──────── specialist-dispatch-gate summary ────────"
+echo "pass=$PASS fail=$FAIL"
+[ "$FAIL" -eq 0 ]

package/payload/platform/plugins/admin/hooks/html-structure-gate.sh

@@ -0,0 +1,165 @@
+#!/usr/bin/env bash
+# html-structure-gate — PreToolUse gate on Write / Edit / MultiEdit.
+#
+# Refuses a write that would produce an HTML document with a <style> element
+# opened inside another one, or with more openers than closers.
+#
+# The fault is not cosmetic. HTML parses style content as raw text, so the FIRST
+# </style> closes the outer element: everything after it becomes body content and
+# renders as visible text, and the rule immediately after the stray opener is
+# eaten as part of an invalid selector. One fault, two symptoms — a leaked
+# stylesheet above the header and an unstyled box further down the same page.
+#
+# The detector has three rules, and the same three are implemented in the
+# session-manager census that walks what is already on disk:
+#   1. HTML comments are stripped first, each replaced by its own newlines, so a
+#      <style> inside <!-- … --> is not scanned and line numbers do not shift.
+#      That comment case is real: two account templates carry one and are clean,
+#      and a comment-blind detector reports both.
+#   2. <style…> and </style…> are walked case-insensitively, tracking depth. An
+#      opener seen at depth > 0 is the fault.
+#   3. At end of input, openers must equal closers; an unmatched opener is
+#      reported at its own line.
+#
+# It walks the document the call would PRODUCE, not the fragment it carries. For
+# Write that is `content`; for Edit and MultiEdit the on-disk file is read and
+# the replacements applied in memory first. Walking a fragment cannot work: rule
+# 3 would refuse every partial edit, and a nested opener whose outer <style> is
+# already on disk would pass.
+#
+# Scope is the whole account with an exclusion list, never a bucket list: every
+# .html/.htm resolving inside the account dir except under node_modules/,
+# .wrangler/, .tool/ and .trash/. A bucket list is what let the live document
+# through — it sat under sites/<project>/public/, which no quote bucket covers.
+# The account dir is this hook's cwd, as in fs-schema-guard.sh.
+#
+# Exit codes: 0 = allow, 2 = block (stderr shown to the agent). Fail OPEN on an
+# uninspectable envelope — tty, empty stdin, unreadable target, unparseable edit.
+# A gate that bricks writes on a parse failure is worse than the fault it catches.
+#
+# The observability line is a direct append to the resolved server.log, not an
+# echo: a hook's stderr reaches no sink on an allow, so a stderr-only line would
+# be an audit nothing reads. No task numbers or internal refs in operator text.
+
+set -uo pipefail
+
+# No envelope (tty or empty stdin) → allow: cannot inspect, must not brick writes.
+if [ -t 0 ]; then exit 0; fi
+INPUT=$(cat)
+[ -z "$INPUT" ] && exit 0
+
+VERDICT=$(INPUT="$INPUT" ACCT="$PWD" python3 - <<'PY' 2>/dev/null || true
+import os, re, json, sys
+
+COMMENT = re.compile(r"<!--.*?-->", re.S)
+CSS_COMMENT = re.compile(r"/\*.*?\*/", re.S)
+TAG = re.compile(r"<\s*(/)?\s*style\b[^>]*>", re.I)
+EXCLUDED = ("node_modules", ".wrangler", ".tool", ".trash")
+
+
+def fault_line(s):
+    """Line of the first nested or unmatched <style> opener, else None."""
+    t = COMMENT.sub(lambda m: "\n" * m.group(0).count("\n"), s)
+    spans = [(m.start(), m.end()) for m in CSS_COMMENT.finditer(t)]
+    depth = 0
+    open_line = 0
+    for m in TAG.finditer(t):
+        line = t.count("\n", 0, m.start()) + 1
+        if m.group(1):
+            if depth > 0:
+                depth -= 1
+        elif depth > 0:
+            # A CSS comment protects an opener but never a closer. Style content
+            # is raw text to the HTML parser, so </style> terminates the element
+            # wherever it appears; an opener is never a parse event there, only
+            # text the CSS parser reads as an invalid selector — and inside a
+            # comment it is discarded, so nothing is eaten.
+            if any(a <= m.start() < b for a, b in spans):
+                continue
+            return line
+        else:
+            depth = 1
+            open_line = line
+    return open_line if depth > 0 else None
+
+
+try:
+    d = json.loads(os.environ["INPUT"])
+except Exception:
+    sys.exit(0)
+if (d.get("tool_name", "") or "") not in ("Write", "Edit", "MultiEdit"):
+    sys.exit(0)
+tool = d["tool_name"]
+ti = d.get("tool_input", {}) or {}
+target = ti.get("file_path") or ""
+if not target:
+    sys.exit(0)
+
+acct = os.path.realpath(os.environ["ACCT"])
+ab = os.path.realpath(target if os.path.isabs(target) else os.path.join(acct, target))
+if not ab.startswith(acct + os.sep):
+    sys.exit(0)
+rel = os.path.relpath(ab, acct)
+if os.path.splitext(rel)[1].lower() not in (".html", ".htm"):
+    sys.exit(0)
+if any(p in EXCLUDED for p in rel.split(os.sep)):
+    sys.exit(0)
+
+if tool == "Write":
+    produced = ti.get("content")
+    if not isinstance(produced, str):
+        sys.exit(0)
+else:
+    try:
+        with open(ab, encoding="utf-8", errors="replace") as fh:
+            produced = fh.read()
+    except Exception:
+        sys.exit(0)
+    edits = ti.get("edits") if tool == "MultiEdit" else [ti]
+    if not isinstance(edits, list):
+        sys.exit(0)
+    for e in edits:
+        if not isinstance(e, dict):
+            sys.exit(0)
+        old, new = e.get("old_string"), e.get("new_string")
+        if not isinstance(old, str) or not isinstance(new, str):
+            sys.exit(0)
+        produced = produced.replace(old, new) if e.get("replace_all") else produced.replace(old, new, 1)
+
+line = fault_line(produced)
+if line is None:
+    sys.exit(0)
+print(line)
+print(json.dumps(rel))
+PY
+)
+
+[ -z "$VERDICT" ] && exit 0
+LINE=$(printf '%s' "$VERDICT" | sed -n 1p)
+QREL=$(printf '%s' "$VERDICT" | sed -n 2p)
+[ -z "$LINE" ] && exit 0
+
+# Sink ladder, as quote-render-pdf-conformance.sh: LOG_DIR is stamped on the
+# rc-spawn path, CLAUDE_SESSION_MANAGER_PERSIST_DIR is on the systemd unit and
+# resolves to the same directory, the account's own logs dir is the last resort.
+#
+# There is deliberately no hard-coded brand fallback. Four brands are co-resident
+# on one box, each with its own ~/.<brand>/logs, so a literal would file this
+# account's path in a SIBLING brand's server.log. When no rung resolves, the line
+# is dropped: the refusal still blocks and still reaches the agent on stderr.
+LOGD=""
+if [ -n "${LOG_DIR:-}" ] && [ -d "${LOG_DIR}" ]; then
+  LOGD="$LOG_DIR"
+elif [ -n "${CLAUDE_SESSION_MANAGER_PERSIST_DIR:-}" ] && [ -d "${CLAUDE_SESSION_MANAGER_PERSIST_DIR}/logs" ]; then
+  LOGD="$CLAUDE_SESSION_MANAGER_PERSIST_DIR/logs"
+elif [ -d "$PWD/logs" ]; then
+  LOGD="$PWD/logs"
+fi
+if [ -n "$LOGD" ]; then
+  ID8=$(basename "$PWD" | cut -c1-8)
+  printf '[html-structure-gate] op=refuse account=%s file=%s line=%s\n' \
+    "$ID8" "$QREL" "$LINE" >>"$LOGD/server.log" 2>/dev/null || true
+fi
+
+echo "Blocked: this document opens a <style> element inside another one (line $LINE). The browser closes the outer element at the first </style>, so the rest of the stylesheet renders as visible text on the page and the rule after the stray opener is discarded. Put the block in the body as its own <style> element, or merge its rules into the one already open." >&2
+exit 2

package/payload/platform/plugins/admin/hooks/quote-render-pdf-conformance.sh

@@ -4,20 +4,37 @@
 # The companion to the PreToolUse quote-render-gate: that gate checks the
 # rendered HTML on the deterministic path (via the render receipt) before the
 # PDF is printed; the HTML the tool gated cannot yet be a PDF at PreToolUse, so
-# the two PDF-only conformance checks run here, once the PDF exists.
+# the PDF-only conformance checks run here, once the PDF exists.
 #
-# For a gated client-quote PDF (memory/users/<phone>/documents/quote-<jobId>.pdf
-# or ...-breakdown.pdf) whose render receipt names the source HTML, it asserts:
-#   1. the PDF's /URI annotation count >= the source HTML's absolute-link count
+# PAGE CHROME — receipt-free and path-agnostic, so it also covers template-seeded
+# documents (budget estimates, valuations, works orders) that never pass through
+# the quote renderer. Each check gates only a document that DECLARES the thing it
+# checks, so a brochure is never touched:
+#   1. a running header on every physical page, when the source declares a text
+#      margin box. Chrome decides pagination at print time, so a header placed
+#      next to a hand-declared page break misses every bleed page.
+#   2. that header's image no wider than a third of the page, when the source
+#      declares an image margin box. Chromium paints a margin box's content:url()
+#      at intrinsic pixel size and does NOT scale it to the declared box.
+# Both are offline, and both report before either exits, so one print surfaces
+# both faults rather than the second appearing only after the first is reprinted.
+#
+# LINKS — for a gated client-quote PDF (memory/users/<phone>/documents/
+# quote-<jobId>.pdf or ...-breakdown.pdf) whose render receipt names the source:
+#   3. the PDF's /URI annotation count >= the source HTML's absolute-link count
 #      (a print that dropped links — a rasterised or flattened copy — carries
 #      fewer /URI than the HTML had anchors);
-#   2. every embedded https:// anchor in the source HTML answers 200 (a pending
+#   4. every embedded https:// anchor in the source HTML answers 200 (a pending
 #      redeploy that would 404 the Sign-Online link is caught before the PDF is
 #      sent).
 # The /URI-count check is offline and runs first; the network fetch runs only
 # when the count check passes, so a link-loss regression never depends on the
 # network being up.
 #
+# Every path that inspects nothing emits `op=skip reason=…`: a silent return is
+# indistinguishable from a gate that never ran, which is the state an account
+# with a stale PostToolUse matcher is actually in.
+#
 # Exit codes: 0 = allow, 2 = block (stderr shown to the agent). Fail OPEN on any
 # uninspectable call (tty / empty stdin / no python3 / no receipt / PDF not
 # written): the no-receipt case is already the PreToolUse gate's to block, and
@@ -184,16 +201,73 @@ for p in range(first, pages + 1):
         missing.append(p)
 
 checked = pages - first + 1
+print("LOG|op=pdf-header-conformance file=%s pages=%d pagesChecked=%d pagesHeaderless=%d"
+      % (base, pages, checked, len(missing)))
 if missing:
-    print("LOG|op=pdf-header-conformance file=%s pages=%d pagesChecked=%d pagesHeaderless=%d"
-          % (base, pages, checked, len(missing)))
-    out("HBLOCK|%s|pagesHeaderless=%d pages=%s"
-        % (base, len(missing), ",".join(str(x) for x in missing)))
-out("LOG|op=pdf-header-conformance file=%s pages=%d pagesChecked=%d pagesHeaderless=0"
-    % (base, pages, checked))
+    print("HBLOCK|%s|pagesHeaderless=%d pages=%s"
+          % (base, len(missing), ",".join(str(x) for x in missing)))
+
+# --- running-image geometry -------------------------------------------------
+# Chromium paints a page-margin box's content:url() at INTRINSIC pixel size (one
+# image px to one CSS px at 96 px/in) and does NOT scale it to the box's declared
+# width/height, so a full-resolution logo covers most of the page on every page
+# the box paints. Measured 2026-08-05 on a real print: a 700x252 asset in a
+# declared 34mm box rendered 525.0 pt wide on a 594.96 pt A4 page, 88%.
+#
+# The assertion is scoped to the RUNNING image — the object present on every
+# checked page, which is what a running header is by construction — never to
+# every image. A content photo legitimately runs wider: measured across three
+# real quotes, running headers occupy 9.0% to 18.9% of page width while
+# single-page content photos occupy 38.7% to 77.2%, so a whole-page threshold
+# blocks legitimate documents while the recurrence-scoped one separates the
+# correct case from the defect by more than four to one.
+#
+# This runs after the header verdict rather than instead of it, so one print
+# reports a headerless page AND an oversized logo together. Both are offline, so
+# the file's offline-before-network ordering still holds.
+if re.search(r'@top-(?:left|center|right)\s*\{[^}]*?content\s*:\s*url\(', doc, re.S) and checked >= 2:
+    try:
+        listing = subprocess.run(["pdfimages", "-list", pdf],
+                                 capture_output=True, text=True, timeout=30).stdout
+    except Exception:
+        listing = ""
+    if not listing:
+        out("LOG|op=pdf-image-geometry file=%s pagesChecked=0 reason=no-poppler" % base)
+    # Columns, zero-based: 0 page, 3 width, 10 object, 12 x-ppi. A row whose
+    # object or ppi is not numeric (an inline image) is skipped rather than
+    # guessed at.
+    per = {}
+    for row in listing.splitlines()[2:]:
+        f = row.split()
+        if len(f) < 13:
+            continue
+        try:
+            pg, wpx, obj, ppi = int(f[0]), int(f[3]), f[10], float(f[12])
+        except ValueError:
+            continue
+        if pg < first or pg > pages or ppi <= 0:
+            continue
+        seen = per.setdefault(obj, {})
+        seen[pg] = max(seen.get(pg, 0.0), wpx / ppi * 72.0)
+    limit = pw / 3.0
+    running = {o: max(v.values()) for o, v in per.items() if len(v) == checked}
+    widest = max(running.values()) if running else 0.0
+    over = sorted(w for w in running.values() if w > limit)
+    # Logged whether or not it fails: this is the line that decides the verdict.
+    print("LOG|op=pdf-image-geometry file=%s pagesChecked=%d runningImages=%d "
+          "widestPt=%.1f fracPage=%.1f%% limitPt=%.1f"
+          % (base, checked, len(running), widest, widest / pw * 100.0, limit))
+    if over:
+        print("GBLOCK|%s|widestPt=%.1f fracPage=%.1f%% limitPt=%.1f"
+              % (base, over[-1], over[-1] / pw * 100.0, limit))
+sys.exit(0)
 PY
 )
 
+# Both page-chrome faults are collected before exiting, so a document with a
+# headerless page AND an oversized running logo reports both on one print rather
+# than surfacing the second only after the first is fixed and reprinted.
+BLOCKED=0
 while IFS= read -r hline; do
   case "$hline" in
     LOG\|*) emit_log "${hline#LOG|}" ;;
@@ -203,32 +277,49 @@ while IFS= read -r hline; do
       hdetail=${hrest#*|}
       emit_log "op=bypass file=$hfile reason=pdf-header-conformance detail=$hdetail"
       echo "Blocked: this printed document has physical pages carrying no running header, so it would go out with unbranded pages ($hdetail). The header must be a property of the page itself, a page margin box, not a header block placed next to a declared page break, because the browser decides the real page boundaries at print time. Fix the document's print CSS, print it again, and check every page." >&2
-      exit 2
+      BLOCKED=1
+      ;;
+    GBLOCK\|*)
+      grest=${hline#GBLOCK|}
+      gfile=${grest%%|*}
+      gdetail=${grest#*|}
+      emit_log "op=bypass file=$gfile reason=pdf-header-image-geometry detail=$gdetail"
+      echo "Blocked: the running header image on this printed document covers most of the page width ($gdetail). An image used as a page margin box's content is painted at its own pixel size and is not scaled down to the box you declared, so the image file itself has to be made the size the box expects. Shrink the asset, rebuild the document, print it again, and check a page after the first." >&2
+      BLOCKED=1
       ;;
   esac
 done <<< "$HRESULT"
+[ "$BLOCKED" -eq 1 ] && exit 2
 
 RESULT=$(INPUT="$INPUT" BASE="$PWD" python3 - <<'PY' 2>/dev/null || true
 import os, json, re, sys, urllib.request
 
+# Every return that inspects nothing names its reason. A silent return is
+# indistinguishable from a gate that never ran at all, which is the state a
+# stale PostToolUse matcher leaves an account in; fail-open behaviour itself is
+# unchanged, only its visibility.
+def skip(reason):
+    print("SKIP|%s" % reason)
+    sys.exit(0)
+
 try:
     d = json.loads(os.environ["INPUT"])
 except Exception:
-    sys.exit(0)  # uninspectable envelope -> fail open
+    skip("bad-envelope")
 
 tool = d.get("tool_name", "") or ""
 if not tool.endswith("browser-pdf-save"):
-    sys.exit(0)
+    skip("not-browser-tool")
 path = (d.get("tool_input", {}) or {}).get("path", "") or ""
 if not path:
-    sys.exit(0)
+    skip("no-path")
 norm = os.path.normpath(path)
 m = re.search(r'(?:^|/)memory/users/[^/]+/documents/quote-(.+?)(-breakdown)?\.pdf$', norm)
 if not m:
-    sys.exit(0)  # not a gated client-quote artefact
+    skip("not-gated")  # not a gated client-quote artefact
 jobid = m.group(1)
 if "/" in jobid or ".." in jobid:
-    sys.exit(0)  # the PreToolUse gate owns bad-jobid; here fail open
+    skip("bad-jobid")  # the PreToolUse gate owns bad-jobid; here fail open
 variant = m.group(2)  # "-breakdown" or None
 
 base = os.environ["BASE"]
@@ -236,12 +327,12 @@ receipt_path = os.path.join(base, "quoting", "jobs", jobid, "render-receipt.json
 try:
     receipt = json.load(open(receipt_path))
 except Exception:
-    sys.exit(0)  # no receipt -> PreToolUse gate already blocks; fail open
+    skip("no-receipt")  # PreToolUse gate already blocks that; fail open here
 
 filed = receipt.get("filed", {}) or {}
 html_path = filed.get("breakdown" if variant else "quote", "")
 if not html_path or not os.path.isfile(html_path) or not os.path.isfile(path):
-    sys.exit(0)  # nothing to compare against -> fail open
+    skip("no-source")  # nothing to compare against -> fail open
 
 html = open(html_path, encoding="utf-8", errors="replace").read()
 # Anchors that become a /URI annotation in the printed PDF: absolute http(s) or
@@ -274,6 +365,7 @@ PY
 )
 
 case "$RESULT" in
+  SKIP\|*) emit_log "op=skip reason=${RESULT#SKIP|}" ;;
   BLOCK\|*)
     rest=${RESULT#BLOCK|}
     jobid=${rest%%|*}