@rubytech/create-maxy-code 0.1.568 → 0.1.570

package/payload/platform/plugins/admin/hooks/__tests__/quote-render-gate.test.sh

@@ -2,22 +2,44 @@
 # Regression test for quote-render-gate.sh.
 #
 # The gate is a PreToolUse hook on browser-pdf-save. It refuses a client-facing
-# quote PDF (memory/users/<phone>/documents/quote-<jobId>.pdf or
-# ...-breakdown.pdf) unless a render receipt exists for that jobId — proof the
-# deterministic quote-render path produced it. Everything else passes.
+# quote PDF unless the deterministic quote-render path produced that exact
+# document — proven by comparing the PDF's source HTML against the documents
+# the job's render receipt says were filed.
+#
+# Two facts the earlier version of this gate missed, both from a quote that
+# reached a customer hand-authored:
+#
+#   1. Scope. Client quotes are filed under the jobs bucket
+#      (jobs/<jobId>/quote/, jobs/<jobId>/Quotations/), not only under the
+#      customer documents scope. Both paths were printed that evening; the
+#      unmatched one was the one that was sent.
+#   2. Identity. A receipt proves a render happened for the job, not that this
+#      file is its output. The job's figures were rewritten after the render and
+#      the delivered document was written later still, so an existence check
+#      would have authorised the print.
 #
 # Covers:
-#   A. client quote PDF, no receipt              → BLOCKED (exit 2)
-#   B. client quote PDF, receipt present         → ALLOWED (exit 0)
-#   C. client breakdown PDF, no receipt          → BLOCKED
-#   D. client breakdown PDF, receipt present     → ALLOWED
-#   E. non-quote PDF in the documents scope      → ALLOWED (not a quote artefact)
-#   F. internal quote PDF (admin scope)          → ALLOWED (not client-facing)
-#   G. quote-named PDF outside the client scope  → ALLOWED (only the documents scope is gated)
-#   H. empty stdin                               → ALLOWED (general-purpose tool, fail-open)
-#   I. a non-browser tool                        → ALLOWED (matcher defence-in-depth)
-#   J. jobId carrying a path traversal           → BLOCKED (never resolves a stray receipt)
-#   K. a block emits the op=bypass fault line
+#   A. jobs-bucket PDF whose source matches filed.quote      → ALLOWED
+#   B. jobs-bucket PDF, hand-authored source                 → BLOCKED not-receipt-filed
+#   C. jobs-bucket PDF with no source HTML beside it         → BLOCKED no-source-html
+#   D. jobs-bucket PDF whose source matches filed.internal   → BLOCKED (not client-facing)
+#   E. Quotations bucket, source matches filed.quote         → ALLOWED
+#   F. jobs-bucket PDF whose source matches filed.breakdown  → ALLOWED
+#   G. the internal pricing bucket                           → ALLOWED (never gated)
+#   H. customer documents scope, source matches filed.quote  → ALLOWED
+#   I. customer documents scope, no receipt for the job      → BLOCKED
+#   J. a non-quote PDF in the documents scope                → ALLOWED
+#   K. the admin-scope internal view                         → ALLOWED
+#   L. empty stdin                                           → ALLOWED (fail-open)
+#   M. a non-browser tool                                    → ALLOWED
+#   N. jobId carrying a path traversal                       → BLOCKED bad-jobid
+#   N2. a PDF nested one level deeper in the quote bucket → BLOCKED
+#       (the write gate and the Bash gate both match the bucket recursively;
+#        a print gate that matched only direct children would disagree with
+#        them, and one mkdir would walk a hand-authored quote straight out)
+#   O. the recorded incident: a hand-authored quote carrying no marker at all,
+#      which a marker check would have passed
+#   P. a block emits the op=bypass fault line with its reason
 
 set -u
 
@@ -31,17 +53,34 @@ ACCT=$(mktemp -d)
 cleanup() { rm -rf "$ACCT"; }
 trap cleanup EXIT
 
-# A receipt for job-1 (present) — jobs job-2 / job-3 have none.
-mkdir -p "$ACCT/quoting/jobs/job-1"
-printf '{"jobId":"job-1"}' > "$ACCT/quoting/jobs/job-1/render-receipt.json"
-
 DOCS="$ACCT/memory/users/44700900000/documents"
 ADMIN="$ACCT/memory/admin/customers/44700900000"
+JOB="$ACCT/jobs/job-1"
+
+mkdir -p "$DOCS" "$ADMIN" "$JOB/quote" "$JOB/Quotations" "$JOB/pricing" "$ACCT/quoting/jobs/job-1"
+
+# The three documents a successful render files, each with distinct content.
+printf '<html data-quote-total="1">rendered client quote</html>' > "$DOCS/quote-job-1.html"
+printf '<html>rendered breakdown</html>'                          > "$DOCS/quote-job-1-breakdown.html"
+printf '<html data-internal-only="1">rendered internal</html>'    > "$ADMIN/quote-job-1-internal.html"
+
+cat > "$ACCT/quoting/jobs/job-1/render-receipt.json" <<'RECEIPT'
+{
+  "jobId": "job-1",
+  "engineTotal": 1000,
+  "filed": {
+    "internal":  "memory/admin/customers/44700900000/quote-job-1-internal.html",
+    "breakdown": "memory/users/44700900000/documents/quote-job-1-breakdown.html",
+    "quote":     "memory/users/44700900000/documents/quote-job-1.html"
+  },
+  "renderedAt": "2026-08-06T00:00:00.000Z"
+}
+RECEIPT
 
 PASS=0
 FAIL=0
 
-# Run the hook with cwd = the account dir (as the PTY does), capturing exit + stderr.
+# Run the hook with cwd = the account dir (as the PTY does), capturing exit.
 run_case() {
   local name="$1" stdin="$2" expected_exit="$3"
   local actual_exit
@@ -62,46 +101,103 @@ envelope() { # tool_name, path
 
 BROWSER="mcp__plugin_browser_browser__browser-pdf-save"
 
-run_case "A: client quote PDF, no receipt → BLOCKED" \
-  "$(envelope "$BROWSER" "$DOCS/quote-job-2.pdf")" 2
-
-run_case "B: client quote PDF, receipt present → ALLOWED" \
+# A — a rendered document copied into the jobs bucket reconciles by content.
+cp "$DOCS/quote-job-1.html" "$JOB/quote/Q 1879 - Client.html"
+run_case "A: jobs bucket, source matches filed.quote → ALLOWED" \
+  "$(envelope "$BROWSER" "$JOB/quote/Q 1879 - Client.pdf")" 0
+
+# B — the same path, hand-authored.
+printf '<html>hand-authored quote</html>' > "$JOB/quote/Q 1879 - Client.html"
+run_case "B: jobs bucket, hand-authored source → BLOCKED" \
+  "$(envelope "$BROWSER" "$JOB/quote/Q 1879 - Client.pdf")" 2
+
+# C — no source beside the PDF at all.
+rm -f "$JOB/quote/Q 1879 - Client.html"
+run_case "C: jobs bucket, no source HTML → BLOCKED" \
+  "$(envelope "$BROWSER" "$JOB/quote/Q 1879 - Client.pdf")" 2
+
+# D — the internal view is filed, but it is not client-facing.
+cp "$ADMIN/quote-job-1-internal.html" "$JOB/quote/Q 1879 - Client.html"
+run_case "D: jobs bucket, source matches filed.internal → BLOCKED" \
+  "$(envelope "$BROWSER" "$JOB/quote/Q 1879 - Client.pdf")" 2
+
+# E — the Quotations bucket is the same convention.
+cp "$DOCS/quote-job-1.html" "$JOB/Quotations/Q 1879 - Client.html"
+run_case "E: Quotations bucket, source matches filed.quote → ALLOWED" \
+  "$(envelope "$BROWSER" "$JOB/Quotations/Q 1879 - Client.pdf")" 0
+
+# F — the breakdown is client-facing too.
+cp "$DOCS/quote-job-1-breakdown.html" "$JOB/quote/breakdown.html"
+run_case "F: jobs bucket, source matches filed.breakdown → ALLOWED" \
+  "$(envelope "$BROWSER" "$JOB/quote/breakdown.pdf")" 0
+
+# G — the internal priced breakdown is never gated.
+printf '<html>internal pricing</html>' > "$JOB/pricing/breakdown.html"
+run_case "G: internal pricing bucket → ALLOWED" \
+  "$(envelope "$BROWSER" "$JOB/pricing/breakdown.pdf")" 0
+
+run_case "H: documents scope, source matches filed.quote → ALLOWED" \
   "$(envelope "$BROWSER" "$DOCS/quote-job-1.pdf")" 0
 
-run_case "C: client breakdown PDF, no receipt → BLOCKED" \
-  "$(envelope "$BROWSER" "$DOCS/quote-job-3-breakdown.pdf")" 2
-
-run_case "D: client breakdown PDF, receipt present → ALLOWED" \
-  "$(envelope "$BROWSER" "$DOCS/quote-job-1-breakdown.pdf")" 0
+run_case "I: documents scope, no receipt for the job → BLOCKED" \
+  "$(envelope "$BROWSER" "$DOCS/quote-job-2.pdf")" 2
 
-run_case "E: non-quote PDF in documents scope → ALLOWED" \
+printf '<html>brochure</html>' > "$DOCS/brochure.html"
+run_case "J: non-quote PDF in documents scope → ALLOWED" \
   "$(envelope "$BROWSER" "$DOCS/brochure.pdf")" 0
 
-run_case "F: internal quote PDF (admin scope) → ALLOWED" \
-  "$(envelope "$BROWSER" "$ADMIN/quote-job-2-internal.pdf")" 0
+run_case "K: admin-scope internal view → ALLOWED" \
+  "$(envelope "$BROWSER" "$ADMIN/quote-job-1-internal.pdf")" 0
 
-run_case "G: quote-named PDF outside client scope → ALLOWED" \
-  "$(envelope "$BROWSER" "$ACCT/quote-job-2.pdf")" 0
+run_case "L: empty stdin → ALLOWED (fail-open)" "" 0
 
-run_case "H: empty stdin → ALLOWED (fail-open)" \
-  "" 0
-
-run_case "I: non-browser tool → ALLOWED" \
+run_case "M: non-browser tool → ALLOWED" \
   '{"hook_event_name":"PreToolUse","tool_name":"Write","tool_input":{"file_path":"/x/memory/users/44700900000/documents/quote-job-2.pdf"}}' 0
 
-run_case "J: jobId path traversal → BLOCKED" \
+run_case "N: jobId path traversal → BLOCKED" \
   "$(envelope "$BROWSER" "$DOCS/quote-...pdf")" 2
 
-# K: a block emits the op=bypass fault line on stderr.
-STDERR=$( cd "$ACCT" && printf '%s' "$(envelope "$BROWSER" "$DOCS/quote-job-2.pdf")" | bash "$HOOK" 2>&1 >/dev/null )
-if printf '%s' "$STDERR" | grep -q '\[quote-render\] op=bypass jobId=job-2'; then
-  echo "PASS: K: block emits op=bypass jobId=job-2"
-  PASS=$((PASS + 1))
-else
-  echo "FAIL: K: op=bypass line absent (got: $STDERR)" >&2
+# N2 — nesting must not escape the bucket.
+mkdir -p "$JOB/quote/final"
+printf '<html>hand-authored</html>' > "$JOB/quote/final/Q 1879 - Client.html"
+run_case "N2: a PDF nested deeper in the quote bucket → BLOCKED" \
+  "$(envelope "$BROWSER" "$JOB/quote/final/Q 1879 - Client.pdf")" 2
+
+cp "$DOCS/quote-job-1.html" "$JOB/quote/final/Q 1879 - Client.html"
+run_case "N2: a nested rendered copy still reconciles → ALLOWED" \
+  "$(envelope "$BROWSER" "$JOB/quote/final/Q 1879 - Client.pdf")" 0
+
+# O — the recorded incident. The delivered document carried zero
+# data-quote-total, so a marker check would have passed it; only a content
+# comparison against the receipt-filed documents rejects it.
+printf '<html>Q 1879 Woolgrove hand-authored, no markers</html>' > "$JOB/quote/Woolgrove.html"
+run_case "O: recorded incident, hand-authored and markerless → BLOCKED" \
+  "$(envelope "$BROWSER" "$JOB/quote/Woolgrove.pdf")" 2
+if grep -q 'data-quote-total' "$JOB/quote/Woolgrove.html"; then
+  echo "FAIL: O: the incident fixture must carry no marker" >&2
   FAIL=$((FAIL + 1))
+else
+  echo "PASS: O: the incident fixture carries no marker, so a marker check would pass it"
+  PASS=$((PASS + 1))
 fi
 
+# P — a block names its reason on stderr.
+check_reason() { # name, path, expected reason
+  local out
+  out=$( cd "$ACCT" && printf '%s' "$(envelope "$BROWSER" "$2")" | bash "$HOOK" 2>&1 >/dev/null )
+  if printf '%s' "$out" | grep -q "\[quote-render\] op=bypass jobId=.* reason=$3"; then
+    echo "PASS: P: $1 emits reason=$3"
+    PASS=$((PASS + 1))
+  else
+    echo "FAIL: P: $1 did not emit reason=$3 (got: $out)" >&2
+    FAIL=$((FAIL + 1))
+  fi
+}
+check_reason "hand-authored source" "$JOB/quote/Woolgrove.pdf" "not-receipt-filed"
+rm -f "$JOB/quote/Woolgrove.html"
+check_reason "missing source" "$JOB/quote/Woolgrove.pdf" "no-source-html"
+check_reason "path traversal" "$DOCS/quote-...pdf" "bad-jobid"
+
 echo "──────── quote-render-gate test summary ────────"
 echo "PASS=$PASS FAIL=$FAIL"
 [[ "$FAIL" -eq 0 ]]

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

@@ -17,6 +17,18 @@
 #   G. empty stdin                                    → ALLOWED (fail-open)
 #   H. non-browser tool                               → ALLOWED (matcher defence-in-depth)
 #   I. a block emits the op=bypass fault line
+#
+# Per-physical-page running-header conformance (receipt-free, so it also covers
+# template-seeded documents that never pass through the quote renderer):
+#   J. header text on every checked physical page     → ALLOWED
+#   K. one physical page without it (a bleed page)    → BLOCKED
+#   L. source HTML declares no running header         → ALLOWED (never gated)
+#   M. no receipt and no sibling HTML                 → ALLOWED (fail-open)
+#   N. single-page document under @page :first        → ALLOWED (nothing to check)
+#   O. a clean run logs pagesChecked / pagesHeaderless
+#   P. a block names the headerless page numbers
+#   Q. a running footer repeating the ref does NOT count as a header
+#   R. @page :first declared before @page still yields the marker
 
 set -u
 
@@ -47,6 +59,42 @@ mk_job() { # jobId, html_body, pdf_uri_repeat
     > "$DOCS/quote-$job.pdf"
 }
 
+# A minimal, uncompressed, multi-page PDF. Each page argument is
+# "<top line>|<bottom line>"; the bottom line is optional and stands in for a
+# running footer. The /URI stubs above are not readable by pdftotext, and the
+# header check needs real per-page text at real positions, so the header
+# fixtures need a genuine PDF. Pure stdlib — no third-party generator, no
+# network, deterministic byte-for-byte.
+mk_pdf() { # out_path, then one "top|bottom" argument per page
+  local out="$1"; shift
+  python3 - "$out" "$@" <<'PY'
+import sys
+out, texts = sys.argv[1], sys.argv[2:]
+objs = []
+kids = " ".join("%d 0 R" % (4 + 2 * i) for i in range(len(texts)))
+objs.append("<< /Type /Catalog /Pages 2 0 R >>")
+objs.append("<< /Type /Pages /Kids [%s] /Count %d >>" % (kids, len(texts)))
+objs.append("<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica >>")
+for i, t in enumerate(texts):
+    top, _, bottom = t.partition("|")
+    body = "BT /F1 11 Tf 72 760 Td (%s) Tj ET" % top
+    if bottom:
+        body += " BT /F1 8 Tf 72 40 Td (%s) Tj ET" % bottom
+    objs.append("<< /Type /Page /Parent 2 0 R /MediaBox [0 0 595 842] "
+                "/Resources << /Font << /F1 3 0 R >> >> /Contents %d 0 R >>" % (5 + 2 * i))
+    objs.append("<< /Length %d >>\nstream\n%s\nendstream" % (len(body), body))
+pdf, offsets = "%PDF-1.4\n", []
+for i, o in enumerate(objs, start=1):
+    offsets.append(len(pdf))
+    pdf += "%d 0 obj\n%s\nendobj\n" % (i, o)
+start = len(pdf)
+pdf += "xref\n0 %d\n0000000000 65535 f \n" % (len(objs) + 1)
+pdf += "".join("%010d 00000 n \n" % off for off in offsets)
+pdf += "trailer\n<< /Size %d /Root 1 0 R >>\nstartxref\n%d\n%%%%EOF\n" % (len(objs) + 1, start)
+open(out, "wb").write(pdf.encode("latin-1"))
+PY
+}
+
 # C: no absolute links, PDF has none → allow.
 mk_job "clean" '<html><body><a href="#top">top</a><p>no links</p></body></html>' 0
 # D: two https links, PDF dropped them (0 /URI) → block on count.
@@ -94,6 +142,72 @@ else
   echo "FAIL: I: op=bypass line absent (got: $STDERR)" >&2; FAIL=$((FAIL + 1))
 fi
 
+# ---- per-physical-page running-header conformance ----
+# A source document that declares its running header in @page top margin boxes,
+# with @page :first blanking them so page 1 keeps its own masthead.
+HDR_CSS='<style>@page{@top-left{content:url("data:image/png;base64,AA");}@top-center{content:"Quote 2468/1";}}@page :first{@top-center{content:"";}}</style>'
+NOHDR_CSS='<style>@page{@bottom-center{content:"footer only";}}</style>'
+
+mk_doc() { # basename, css, then one text line per physical page
+  local base="$1" css="$2"; shift 2
+  printf '<html><head>%s</head><body>doc</body></html>' "$css" > "$DOCS/$base.html"
+  mk_pdf "$DOCS/$base.pdf" "$@"
+}
+
+mk_doc "hdr-ok"     "$HDR_CSS"   "cover masthead" "Quote 2468/1 body two" "Quote 2468/1 body three"
+mk_doc "hdr-bleed"  "$HDR_CSS"   "cover masthead" "Quote 2468/1 body two" "orphaned bleed content"
+mk_doc "hdr-none"   "$NOHDR_CSS" "page one" "page two"
+mk_doc "hdr-single" "$HDR_CSS"   "cover only"
+mk_pdf "$DOCS/hdr-orphan.pdf" "page one" "page two"
+
+# R: the same document with @page :first declared BEFORE @page. CSS does not fix
+# the order of the two rules, and the suppression rule declares the same boxes
+# with empty content, so reading only the first declaration of a box would report
+# "no running header" and skip the check entirely.
+FIRST_LAST_CSS='<style>@page :first{@top-center{content:"";}}@page{@top-left{content:url("data:image/png;base64,AA");}@top-center{content:"Quote 2468/1";}}</style>'
+mk_doc "hdr-first-declared-first" "$FIRST_LAST_CSS" \
+  "cover masthead" "Quote 2468/1 body two" "orphaned bleed content"
+
+# Q: the footer repeats the header's reference on every page, and page 3 has no
+# header. A whole-page text match reports this document clean — measured on a
+# real 10-page print, where page 1 matched on its footer alone. The check must
+# look at the top band of the page, so this document is still blocked.
+mk_doc "hdr-footer-decoy" "$HDR_CSS" \
+  "cover masthead|GLS Ltd . Est 1987 . Quote 2468/1" \
+  "Quote 2468/1 body two|GLS Ltd . Est 1987 . Quote 2468/1" \
+  "orphaned bleed content|GLS Ltd . Est 1987 . Quote 2468/1"
+
+run_case "J: header on every checked physical page → ALLOWED" \
+  "$(envelope "$BROWSER" "$DOCS/hdr-ok.pdf")" 0
+run_case "K: a physical page with no header → BLOCKED" \
+  "$(envelope "$BROWSER" "$DOCS/hdr-bleed.pdf")" 2
+run_case "L: document declares no running header → ALLOWED" \
+  "$(envelope "$BROWSER" "$DOCS/hdr-none.pdf")" 0
+run_case "M: no receipt and no sibling HTML → ALLOWED" \
+  "$(envelope "$BROWSER" "$DOCS/hdr-orphan.pdf")" 0
+run_case "N: single-page document → ALLOWED" \
+  "$(envelope "$BROWSER" "$DOCS/hdr-single.pdf")" 0
+run_case "Q: footer repeats the ref, page 3 headerless → BLOCKED" \
+  "$(envelope "$BROWSER" "$DOCS/hdr-footer-decoy.pdf")" 2
+run_case "R: @page :first declared first, page 3 headerless → BLOCKED" \
+  "$(envelope "$BROWSER" "$DOCS/hdr-first-declared-first.pdf")" 2
+
+# O: a clean run is distinguishable from a check that never ran.
+STDERR=$( cd "$ACCT" && printf '%s' "$(envelope "$BROWSER" "$DOCS/hdr-ok.pdf")" | bash "$HOOK" 2>&1 >/dev/null )
+if printf '%s' "$STDERR" | grep -q 'op=pdf-header-conformance .*pagesChecked=2 pagesHeaderless=0'; then
+  echo "PASS: O: clean run logs pagesChecked=2 pagesHeaderless=0"; PASS=$((PASS + 1))
+else
+  echo "FAIL: O: conformance line absent or wrong (got: $STDERR)" >&2; FAIL=$((FAIL + 1))
+fi
+
+# P: a block names the offending physical page.
+STDERR=$( cd "$ACCT" && printf '%s' "$(envelope "$BROWSER" "$DOCS/hdr-bleed.pdf")" | bash "$HOOK" 2>&1 >/dev/null )
+if printf '%s' "$STDERR" | grep -q 'reason=pdf-header-conformance detail=pagesHeaderless=1 pages=3'; then
+  echo "PASS: P: block names the headerless page"; PASS=$((PASS + 1))
+else
+  echo "FAIL: P: block detail wrong (got: $STDERR)" >&2; FAIL=$((FAIL + 1))
+fi
+
 echo "──────── quote-render-pdf-conformance test summary ────────"
 echo "PASS=$PASS FAIL=$FAIL"
 [[ "$FAIL" -eq 0 ]]

package/payload/platform/plugins/admin/hooks/pdf-text-layer-inject.sh

@@ -0,0 +1,137 @@
+#!/usr/bin/env bash
+# pdf-text-layer-inject — PostToolUse companion to Read on a .pdf.
+#
+# Read on a PDF returns rasterised page images and no text, so an agent that
+# needs a value out of a PDF reads it off a picture of the page. A job sheet
+# reached a field engineer with a postcode one letter wrong for exactly that
+# reason, while the correct characters sat in the PDF's own text layer. This
+# hook puts that text layer into the agent's context alongside the images, so
+# no value is transcribed by eye when the characters exist.
+#
+# Exit codes: 2 = the extraction is on stderr and the model reads it (the
+# PostToolUse feedback mechanism mcp-tool-missing.sh already relies on);
+# 0 = nothing to inject. Fail OPEN on every uninspectable path — a hook that
+# cannot read a PDF must never disturb the Read that already succeeded.
+#
+# One line per .pdf Read to <logDir>/pdf-text-layer.log, including the reads
+# that inject nothing: a scanned PDF and a hook that never fired are different
+# states and only the log tells them apart.
+
+set -uo pipefail
+
+if [ -t 0 ]; then exit 0; fi
+INPUT=$(cat)
+[ -z "$INPUT" ] && exit 0
+
+# --- log sink ---------------------------------------------------------------
+# A hook's stderr on exit 0 reaches no file on this platform. The ladder mirrors
+# quote-render-pdf-conformance.sh: LOG_DIR is stamped only on the rc-spawn path,
+# CLAUDE_SESSION_MANAGER_PERSIST_DIR is on the systemd unit and resolves to the
+# same directory, ACCOUNT_DIR/logs is the last resort.
+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 [ -n "${ACCOUNT_DIR:-}" ] && [ -d "${ACCOUNT_DIR}/logs" ]; then
+  LOGD="$ACCOUNT_DIR/logs"
+fi
+
+INPUT="$INPUT" LOGD="$LOGD" \
+NOW_ISO="$(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || echo '?')" \
+CAP="${PDF_TEXT_LAYER_CAP:-100000}" \
+python3 - <<'PY'
+import json, os, subprocess, sys
+
+MIN_TEXT = 20
+
+logd = os.environ.get("LOGD", "")
+now = os.environ.get("NOW_ISO", "?")
+try:
+    cap = int(os.environ.get("CAP", "100000"))
+except Exception:
+    cap = 100000
+
+
+# The log directory is install-wide: LOG_DIR resolves to <persistDir>/logs, one
+# file shared by every account on the box. Without an account field a per-account
+# count is not computable, and a per-account count is the signal that says the
+# settings reconcile never reached an account. ACCOUNT_ID is stamped on both the
+# pty-spawner and rc-daemon spawn paths; ACCOUNT_DIR's basename is the fallback.
+account = os.environ.get("ACCOUNT_ID") or ""
+if not account:
+    acct_dir = os.environ.get("ACCOUNT_DIR") or ""
+    account = os.path.basename(acct_dir.rstrip("/")) if acct_dir else ""
+account = account or "?"
+
+
+def emit_log(base, chars, injected, reason, sid):
+    if not logd:
+        return
+    line = ("%s [pdf-text-layer] op=pdf-text-layer file=%s chars=%d "
+            "injected=%s reason=%s account=%s session=%s"
+            % (now, base, chars, injected, reason, account, sid))
+    try:
+        with open(os.path.join(logd, "pdf-text-layer.log"), "a") as fh:
+            fh.write(line + "\n")
+    except Exception:
+        pass
+
+
+try:
+    d = json.loads(os.environ["INPUT"])
+except Exception:
+    sys.exit(0)
+
+if (d.get("hook_event_name") or "") != "PostToolUse":
+    sys.exit(0)
+if (d.get("tool_name") or "") != "Read":
+    sys.exit(0)
+path = (d.get("tool_input") or {}).get("file_path") or ""
+if not path.lower().endswith(".pdf"):
+    sys.exit(0)
+
+sid = d.get("session_id") or "?"
+base = os.path.basename(path)
+
+try:
+    proc = subprocess.run(["pdftotext", path, "-"], capture_output=True, timeout=60)
+except FileNotFoundError:
+    emit_log(base, 0, "no", "no-poppler", sid)
+    sys.exit(0)
+except Exception:
+    emit_log(base, 0, "no", "unreadable", sid)
+    sys.exit(0)
+
+if proc.returncode != 0:
+    emit_log(base, 0, "no", "unreadable", sid)
+    sys.exit(0)
+
+text = proc.stdout.decode("utf-8", "replace")
+chars = len("".join(text.split()))
+
+if chars < MIN_TEXT:
+    emit_log(base, chars, "no", "scanned-no-text", sid)
+    sys.exit(0)
+
+# Log before writing the payload, so a failure mid-write still leaves the record.
+emit_log(base, chars, "yes", "text-layer", sid)
+
+payload = text
+omitted = 0
+if len(payload) > cap:
+    omitted = len(payload) - cap
+    payload = payload[:cap]
+
+sys.stderr.write(
+    "Text layer of %s, extracted from the PDF itself. Copy values from here, "
+    "not from the page images.\n\n%s" % (base, payload))
+if omitted:
+    sys.stderr.write(
+        "\n\n[%d characters omitted. Run: pdftotext %s -]\n" % (omitted, path))
+sys.stderr.write("\n")
+sys.exit(2)
+PY
+rc=$?
+[ "$rc" -eq 2 ] && exit 2
+exit 0

package/payload/platform/plugins/admin/hooks/quote-path-write-gate.sh

@@ -0,0 +1,137 @@
+#!/usr/bin/env bash
+# quote-path-write-gate — PreToolUse gate on Write / Edit / MultiEdit.
+#
+# The client quote document has one owner, and that ownership is a capability:
+# the quote-render tool is granted to the quoter's card and to no other, so no
+# other agent can produce a receipt-bearing quote by any route. This gate
+# expresses the same rule at the write, refusing an agent that does not hold
+# quote-render from authoring a quote artefact or the account's quote
+# templates. It leaves untouched every other deliverable that agent owns —
+# works orders, heritage statements, survey sheets, drawing registers,
+# trial-pit records, invoice stamps.
+#
+# Scope: jobs/<jobId>/quote/, jobs/<jobId>/Quotations/, quoting/templates/.
+# jobs/<jobId>/pricing/ is excluded — the internal priced breakdown is not a
+# client quote artefact.
+#
+# Caller identity is `agent_type` from the hook envelope, which Claude Code
+# sets when a hook fires inside a subagent. The MAXY_SPECIALIST env is not
+# usable here: it is stamped only when a specialist is spawned as its own PTY
+# process, and the dispatches this gate exists to stop were native Agent-tool
+# subagents that inherit the admin process env, so it reads empty for them.
+#
+# Card lookup spans BOTH registration families. Bundled specialists reach a
+# session through the per-account registry; premium-bundle agents register
+# through plugin manifests and are never written to that registry, so a lookup
+# that skipped the premium root would block the quoter itself. Cards are
+# matched on frontmatter `name:` as well as filename, because the quoter's card
+# is filed as sitedesk--quoter.md and declares `name: quoter`.
+#
+# A write from the main conversation carries no agent_type and the admin seat
+# holds no quote-render, so it is refused: no part of a client quote document
+# is another agent's work, the admin's included.
+#
+# Exit codes: 0 = allow, 2 = block (stderr shown to the agent). Fail OPEN on an
+# uninspectable envelope. No task numbers or internal refs in operator-visible
+# 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
+
+DECISION=$(INPUT="$INPUT" python3 - <<'PY' 2>/dev/null || true
+import os, json, re, sys, glob
+
+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)
+ti = d.get("tool_input", {}) or {}
+target = ti.get("file_path") or ti.get("path") or ""
+if not target:
+    sys.exit(0)
+norm = os.path.normpath(target)
+
+in_scope = bool(
+    re.search(r'(?:^|/)jobs/[^/]+/(?:quote|Quotations)/', norm)
+    or re.search(r'(?:^|/)quoting/templates/', norm)
+)
+if not in_scope:
+    sys.exit(0)
+
+agent = (d.get("agent_type") or "").strip()
+if not agent:
+    print("quote-path-write-without-render-tool")
+    sys.exit(0)
+name = agent.split(":")[-1]
+
+roots = [
+    os.path.join(os.getcwd(), ".claude", "agents"),
+    os.path.join(os.getcwd(), "specialists", "agents"),
+]
+ccd = os.environ.get("CLAUDE_CONFIG_DIR", "")
+if ccd:
+    roots.append(os.path.join(ccd, "agents"))
+pr = os.environ.get("PLATFORM_ROOT", "")
+if pr:
+    roots.extend(sorted(glob.glob(os.path.join(os.path.dirname(pr), "premium-plugins", "*", "agents"))))
+    roots.extend(sorted(glob.glob(os.path.join(pr, "plugins", "*", "agents"))))
+
+
+def card_fields(path):
+    """(name, tools) from a card frontmatter block, or None when there is none."""
+    try:
+        with open(path, encoding="utf-8") as fh:
+            lines = fh.read().split("\n")
+    except Exception:
+        return None
+    if not lines or lines[0].strip() != "---":
+        return None
+    cname = ctools = None
+    for line in lines[1:]:
+        if line.strip() == "---":
+            break
+        m = re.match(r'^name:\s*(.+?)\s*$', line)
+        if m:
+            cname = m.group(1).strip().strip("\x22").strip("\x27")
+        m = re.match(r'^tools:\s*(.+?)\s*$', line)
+        if m:
+            ctools = m.group(1)
+    return (cname, ctools)
+
+
+tools = None
+for root in roots:
+    if not os.path.isdir(root):
+        continue
+    for f in sorted(glob.glob(os.path.join(root, "*.md"))):
+        fields = card_fields(f)
+        if not fields:
+            continue
+        cname, ctools = fields
+        if cname == name or os.path.basename(f)[:-3] == name:
+            tools = ctools or ""
+            break
+    if tools is not None:
+        break
+
+if tools is None:
+    print("quote-path-write-unresolved-agent")
+    sys.exit(0)
+# Match the tool itself, not a substring of a longer name.
+if any(t.strip().endswith("quote-render") for t in tools.split(",")):
+    sys.exit(0)
+print("quote-path-write-without-render-tool")
+PY
+)
+
+[ -z "$DECISION" ] && exit 0
+
+echo "[quote-render] op=bypass reason=$DECISION" >&2
+echo "Blocked: quote documents and quote templates are the quoter's work. Dispatch the quoter for this change; it produces the document through the quote-render tool, which files it with its render receipt." >&2
+exit 2