@rubytech/create-realagent-code 0.1.573 → 0.1.575

package/payload/platform/plugins/admin/hooks/fs-schema-guard-bash-post.sh

@@ -36,9 +36,21 @@
 # shell redirect as its sanctioned path, so flagging that first creation would
 # fire on the one legitimate writer and stay blind to every edit after it.
 #
-# Exit codes: 0 = allow, 2 = feedback to the agent (stderr shown). Fail open
-# (exit 0) when the snapshot is missing or the allowed set is empty. Every block
-# logs: [fs-guard-bash] stray path=<name> reason=<top-level|bad-name>
+# This hook has a second, independent job. The Write/Edit path guard records every
+# cross-account target it refused in this session, and any recorded path that
+# exists on disk now was written by some other route after that refusal. Those are
+# reported as `evaded` and pair with the guard's own `blocked` line on the same
+# path, so a bypass is two grep-able lines rather than a transcript to read. The
+# stray fail-opens below do not gate that check: the path guard refuses a sibling
+# target before it parses any schema, so an account with no SCHEMA.md, and a
+# session whose pre-hook failed open, can both still hold a recorded refusal.
+#
+# Exit codes: 0 = allow, 2 = feedback to the agent (stderr shown). The stray check
+# falls silent when the snapshot is missing or the allowed set is empty; the
+# evasion check falls silent when the ledger is missing or unreadable. Every
+# finding logs one of:
+#   [fs-guard-bash] stray path=<name> reason=<top-level|bad-name>
+#   [fs-guard-bash] evaded path=<abs> reason=cross-account target=<acct8>
 # No task numbers / internal refs in any operator-visible string.
 
 set -uo pipefail
@@ -75,21 +87,18 @@ else
 fi
 SID_SAN=$(printf '%s' "$SESSION_ID" | sed 's/[^A-Za-z0-9_-]/_/g')
 SNAP="$TMP_DIR/maxy-fsguard-snapshot-${SID_SAN}.txt"
-
-# Missing pre-snapshot -> fail open (the pre hook could not run or failed open).
-[ -f "$SNAP" ] || exit 0
+LEDGER="$TMP_DIR/maxy-fsguard-refused-${SID_SAN}.txt"
 
 ACCOUNT_DIR="$PWD"
 
 # Parse the allowed top-level set from the account's seeded SCHEMA.md — the same
-# awk extraction fs-schema-guard.sh uses. Empty/absent -> fail open.
+# awk extraction fs-schema-guard.sh uses.
 ALLOWED=""
 if [ -f "$ACCOUNT_DIR/SCHEMA.md" ]; then
   ALLOWED=$(awk '/^```allowed-top-level$/{f=1;next} /^```$/{f=0} f' "$ACCOUNT_DIR/SCHEMA.md")
 fi
-[ -z "$ALLOWED" ] && exit 0
 
-# Compute this command's findings, each tagged `reason<TAB>name`:
+# Compute this command's stray findings, each tagged `reason<TAB>name`:
 #   top-level : an account-root entry present now, absent from the pre-snapshot,
 #               not in the allowed set (the original stray check).
 #   bad-name  : an immediate child of an operator-data bucket (projects/contacts/
@@ -101,7 +110,16 @@ fi
 #               reconcile's job (it can distinguish backlog from fresh; this hook
 #               cannot, with a top-level-only snapshot). python3 does the set
 #               arithmetic and regex (names may contain spaces).
-FINDINGS=$(ACCOUNT_DIR="$ACCOUNT_DIR" SNAP="$SNAP" ALLOWED="$ALLOWED" python3 -c '
+#
+# A missing pre-snapshot, an empty allowed set, or an unlistable account root
+# leaves this check silent. Each of those fail-opens governs THIS check alone:
+# the ledger check below runs whatever they do, because a session whose pre-hook
+# failed open, and an account with no SCHEMA.md, can both still hold a recorded
+# cross-account refusal — the path guard refuses a sibling target before it parses
+# any schema.
+FINDINGS=""
+if [ -f "$SNAP" ] && [ -n "$ALLOWED" ]; then
+  FINDINGS=$(ACCOUNT_DIR="$ACCOUNT_DIR" SNAP="$SNAP" ALLOWED="$ALLOWED" python3 -c '
 import os, sys, re
 acct = os.environ["ACCOUNT_DIR"]
 try:
@@ -134,14 +152,61 @@ for bucket in ("projects", "contacts", "documents"):
             out.append("bad-name\t" + child)
 
 sys.stdout.write("\n".join(out))
-' 2>/dev/null) || exit 0
+' 2>/dev/null) || FINDINGS=""
+fi
+
+# Evasion check. The path guard records every cross-account target it refused in
+# this session; a recorded path that exists on disk now was written by some other
+# route after the refusal. The path was refused in THIS session by this session's
+# own hook, so existence afterwards is attribution, not inference — no directory
+# is walked and no mtime is read, which is what makes this cheap and sound where a
+# sibling scan is neither. Each reported path is dropped from the ledger so one
+# evasion reports once, not on every later Bash call. A missing, unreadable or
+# unstattable ledger reports nothing.
+EVADED=""
+if [ -f "$LEDGER" ]; then
+  EVADED=$(LEDGER="$LEDGER" ACCOUNT_DIR="$ACCOUNT_DIR" python3 -c '
+import os, sys
+ledger = os.environ["LEDGER"]
+root = os.path.dirname(os.path.realpath(os.environ["ACCOUNT_DIR"]))
+try:
+    with open(ledger) as f:
+        paths = [l for l in f.read().split("\n") if l != ""]
+except Exception:
+    sys.exit(1)
+hit, keep, seen = [], [], set()
+for p in paths:
+    try:
+        landed = os.path.exists(p)
+    except Exception:
+        landed = False
+    if not landed:
+        keep.append(p)
+        continue
+    if p in seen:
+        continue
+    seen.add(p)
+    hit.append(p + "\t" + os.path.relpath(p, root).split(os.sep)[0][:8])
+if hit:
+    try:
+        if keep:
+            with open(ledger, "w") as f:
+                f.write("\n".join(keep) + "\n")
+        else:
+            os.remove(ledger)
+    except Exception:
+        pass
+sys.stdout.write("\n".join(hit))
+' 2>/dev/null) || EVADED=""
+fi
 
-[ -z "$FINDINGS" ] && exit 0
+[ -z "$FINDINGS" ] && [ -z "$EVADED" ] && exit 0
 
 # One log line per finding, then a schema-citing feedback block per reason seen.
 # exit 2 feeds stderr back to the agent.
 TOPLEVEL=""
 BADNAME=""
+EVADEDPATHS=""
 {
   while IFS=$'\t' read -r reason name; do
     [ -z "$reason" ] && continue
@@ -150,11 +215,19 @@ BADNAME=""
       bad-name)  echo "[fs-guard-bash] stray path=$name reason=bad-name";  BADNAME="$BADNAME $name" ;;
     esac
   done <<< "$FINDINGS"
+  while IFS=$'\t' read -r epath etarget; do
+    [ -z "$epath" ] && continue
+    echo "[fs-guard-bash] evaded path=$epath reason=cross-account target=$etarget"
+    EVADEDPATHS="$EVADEDPATHS $epath"
+  done <<< "$EVADED"
   if [ -n "$TOPLEVEL" ]; then
     echo "Blocked: this Bash command created top-level entries that are not allowed in this account's data directory:$TOPLEVEL. The layout is fixed by SCHEMA.md — only the entries listed there are permitted at the top level. Relocate this content under projects/, contacts/, or documents/, and route any reorganisation through the data-manager specialist."
   fi
   if [ -n "$BADNAME" ]; then
     echo "Blocked: this Bash command created names that break the account's naming rule:$BADNAME. Folder and file names under projects/, contacts/, and documents/ use lowercase letters, digits, and hyphens only, with a lowercase file extension. Rename them, or route a reorganisation through the data-manager specialist."
   fi
+  if [ -n "$EVADEDPATHS" ]; then
+    echo "Blocked: this Bash command wrote to a path in another account's data directory that a file edit was refused earlier in this session:$EVADEDPATHS. Another account's data is reachable only through the account-scoped file tools, naming the target account explicitly. Undo this write and redo it through those tools."
+  fi
 } >&2
 exit 2

package/payload/platform/plugins/admin/hooks/fs-schema-guard.sh

@@ -29,6 +29,9 @@
 # Exit codes: 0 = allow, 2 = block (stderr shown to the agent). Fail closed when
 # the tool call cannot be inspected (tty or empty stdin). Every block logs
 #   [fs-guard] blocked path=<rel> reason=<top-level|account-machinery|declared-file|over-deep|bad-name>
+# A cross-account block additionally records the refused absolute path in a
+# per-session ledger under the tmpdir, which the PostToolUse Bash twin reads to
+# report the refusal being walked around by a shell command.
 # No task numbers / internal refs in any operator-visible string.
 
 set -uo pipefail
@@ -98,6 +101,21 @@ IFS=$'\t' read -r VERDICT PAYLOAD XABS <<< "$RESOLVED"
 if [ "$VERDICT" = "xacct" ]; then
   echo "[fs-guard] blocked path=$XABS reason=cross-account target=$(printf '%s' "$PAYLOAD" | cut -c1-8)" >&2
   echo "Blocked: '$XABS' is inside another account's data directory. A file edit reaches this account's data only. Cross-account file work goes through the account-scoped file tools, naming the target account explicitly." >&2
+  # Record the refused path for the PostToolUse Bash twin. The block above is the
+  # verdict and stands whatever happens here: recording is best-effort, refusing
+  # is not. Same tmpdir and session-id sanitisation the two Bash hooks carry, so
+  # all three agree on the filename by construction rather than by comment.
+  SESSION_ID=$(field '' session_id)
+  if [ -n "$SESSION_ID" ]; then
+    if [ -n "${FS_GUARD_BASH_TMPDIR:-}" ]; then
+      TMP_DIR="$FS_GUARD_BASH_TMPDIR"
+    else
+      TMP_DIR="${TMPDIR:-${TMP:-${TEMP:-/tmp}}}"
+      TMP_DIR="${TMP_DIR%/}"
+    fi
+    SID_SAN=$(printf '%s' "$SESSION_ID" | sed 's/[^A-Za-z0-9_-]/_/g')
+    printf '%s\n' "$XABS" >> "$TMP_DIR/maxy-fsguard-refused-${SID_SAN}.txt" 2>/dev/null || true
+  fi
   exit 2
 fi
 

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%%|*}