@rubytech/create-maxy-code 0.1.492 → 0.1.493

package/package.json

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

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

@@ -188,6 +188,7 @@ Tools are available via the `admin` MCP server.
 ## Hooks
 
 - `hooks/quote-render-gate.sh` — **PreToolUse matcher=`mcp__plugin_browser_browser__browser-pdf-save`.** Makes the deterministic quote-render path the only route a client-facing quote PDF can reach a customer. Blocks (exit 2) a `browser-pdf-save` whose output path is a client-quote artefact (`memory/users/<phone>/documents/quote-<jobId>.pdf` or `…-breakdown.pdf`) when no render receipt exists at `quoting/jobs/<jobId>/render-receipt.json` — the receipt `quote-render` writes only after its reconcile / margin-leak / link-liveness gates all pass. A hand-authored quote (the SiteDesk 2026-07-14 bypass: `Write` HTML → `browser-pdf-save`, `quote-render` never called, an internal back-test caveat naming another client folded into the free-text region) has no receipt, so the print is refused rather than delivered. **Block message:** `Blocked: this client quote was not produced by the quote-render tool, so its fixed layout and the reconcile, margin-leak and link-liveness gates never ran. Run quote-render for this job (it files the document and its receipt), then print the client HTML path it returns to PDF.` **Log line** (stderr, on a block): `[quote-render] op=bypass jobId=<jobId> detail=client quote PDF has no render receipt` (or `reason=bad-jobid` when the filename does not resolve to a job). Every non-quote PDF — brochures, invoices, the admin-scope internal view — and the deterministic path itself (receipt present) pass at exit 0. **Fail-open** on an uninspectable call (tty / empty stdin / no `python3`): `browser-pdf-save` is a general-purpose tool and the agent never controls this hook's stdin, so failing open opens no bypass while never bricking unrelated PDFs.
+- `hooks/quote-render-pdf-conformance.sh` — **PostToolUse matcher=`mcp__plugin_browser_browser__browser-pdf-save`.** The PDF-time companion to the PreToolUse `quote-render-gate`: the HTML gates run inside `quote-render` before the receipt, but the two PDF-only conformance checks cannot, because the PDF does not exist until `browser-pdf-save` runs. For a gated client-quote PDF (`memory/users/<phone>/documents/quote-<jobId>.pdf` or `…-breakdown.pdf`) whose render receipt names the source HTML, it blocks (exit 2) when the printed PDF's `/URI` annotation count is below the source HTML's absolute-link count (a rasterised or flattened print that dropped links) or when an embedded `https://` link does not answer 200 (a Sign-Online link a pending redeploy would 404). The offline `/URI`-count check runs first and short-circuits, so a link-loss regression never depends on the network. **Block message:** `Blocked: the printed quote PDF is missing links the document declared, or an embedded link is not live (…). Do not send it. If a Sign-Online link is not live yet, deploy the signing page first; then re-render and re-print so the PDF carries every link the document declares.` **Log line** (stderr, on a block): `[quote-render] op=bypass jobId=<jobId> reason=pdf-link-conformance detail=<uri-count …|link <url> -> <code>>`. Every non-quote PDF, and any call with no receipt (the PreToolUse gate owns that block), passes at exit 0. **Fail-open** on an uninspectable call (tty / empty stdin / no `python3` / receipt or PDF absent). **Reach on upgrade:** `provision-account-dir.sh` writes this PostToolUse matcher only at account-provision time, so accounts provisioned before it landed keep a stale matcher and need a settings backfill (tracked as a follow-up task), the same reach limit the AskUserQuestion carrier gate hit.
 - `hooks/webfetch-preflight.mjs` — short-circuits WebFetch on JS-SPA shells with a structured `WEBFETCH_CANNOT_READ_JS_SPA` error so the agent surfaces a loud failure to the owner instead of paying the 60s extraction timeout. Fail-open on any internal error.
 - `hooks/askuserquestion-investigate-gate.sh` — PreToolUse matcher=`AskUserQuestion`. Blocks the question (exit 2) when no read-only investigation tool has fired since the latest real user turn in the session JSONL. The structural fix for the failure class where the agent fabricates a menu before evidence-gathering (session `c085ec2c-46fb-4b73-8865-68cf85866ea8` 2026-05-22 — "change remote access password" → invented options "Admin PIN / Cloudflare tunnel / WiFi password" with zero prior tool_use; post-correction the agent immediately fired `remote-auth-status` → `ToolSearch` → `remote-auth-set-password`, proving it knew the moves). **Allowlist** (exact, with trailing `__<tool>` suffix-match for namespaced `mcp__plugin_<plugin>_<server>__<tool>` aliases): `ToolSearch`, `Grep`, `Glob`, `Read`, `LS`, `NotebookRead`, `Bash`, `WebFetch`, `WebSearch`, plus the read-only admin / memory MCP tools (`*-status`, `*-list`, `*-read`, `skill-find`, `memory-find-candidates`, `profile-read`, `conversation-list`, `memory-list-attachments`, `memory-read-attachment`). **Block message:** `Blocked: AskUserQuestion requires at least one investigation tool (ToolSearch, Grep, Read, *-list, *-status, *-read, skill-find, ...) earlier in this turn. Search the operator's literal phrase first.` **Log line** (stderr, one per call): `[ask-gate] decision=<allow|block> sessionId=<id8> seen=<csv|-> reason=<allowlist-hit|no-investigation|fail-open-no-transcript|fail-open-parse-error>`. **Fail-open** on missing transcript or parse error — nudges, never bricks the UI.
 - `hooks/askuserquestion-channel-carrier-gate.sh` — PreToolUse matcher=`AskUserQuestion`, registered as a **second command on the same matcher** as the investigate-gate (either exit 2 blocks; the two guard different conditions). Blocks the question (exit 2) when the session has a native channel attached, because the Claude Code channel protocol carries only the two permission methods — there is no carrier for the `AskUserQuestion` elicitation, so on an rc-spawn channel (webchat/WhatsApp/Telegram) session the harness would block the turn awaiting a selection that can never arrive and the reader renders only delivered replies, wedging the turn (live SiteDesk incident session `1a085718` 2026-07-11: `/chat` stalled on the delivered "On it…" ack with no card). **Signal:** the rc-spawn writes the channel MCP registration as a config file in `os.tmpdir()` keyed by session id (`maxy-channel-<sid>.json` / `maxy-webchat-channel-<sid>.json` / `maxy-wa-channel-<sid>.json` / `maxy-telegram-channel-<sid>.json`, `sid` sanitized `[^A-Za-z0-9_-]→_` exactly as the writers do); its presence at tool-call time is the authoritative "channel attached to this session" marker. The hook resolves the tmpdir the way Node's `os.tmpdir()` does (`${TMPDIR:-/tmp}`, trailing slash stripped). Correct in both readings of the claude.ai/code scoping question: a Pi channel process sees the tmpfile (block); a claude.ai/code process on another host never sees the Pi tmpfile (fail-open → allow, that surface can answer the card). **Block message:** `Blocked: this is a native-channel session and AskUserQuestion cannot be delivered over a channel (the channel protocol carries no elicitation card, so the turn would wedge). Ask the same question as prose in your channel reply tool and wait for the operator's next message.` **Log line** (stderr, one per decisive call): `[ask-channel] decision=<allow|block> sessionId=<id8> channel=<attached|none> reason=<channel-attached|no-channel|fail-open-no-envelope|fail-open-no-session>`. **Fail-open** on no envelope, blank session id, or absent channel file — nudges, never bricks the UI. The complementary standing check (`interactive-wedge` in the session manager) catches any un-carried interactive tool_use that slips past this hook; it scans every account's project-slug (not just the boot slug), so a client sub-account channel wedge is covered too. **Reach on upgrade:** `provision-account-dir.sh` writes this matcher only at account-provision time, and the upgrade path re-provisions only the house account — so an account provisioned before this gate landed keeps a stale matcher and re-wedges (live SiteDesk recurrence session `d39a22b0`, account `2078cb54`, 2026-07-15). `setup-account.sh` runs `reconcile_all_accounts_askgate` (`platform/scripts/lib/account-settings-askgate.sh`) on every install to retrofit the carrier gate onto every existing account's `settings.json` — idempotent surgical jq patch of the `AskUserQuestion` matcher, one `[backfill-1683] file=<f> status=<absent|no-hooks|already-set|updated|rewrite-failed>` line per account, contents never echoed.

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

@@ -0,0 +1,99 @@
+#!/usr/bin/env bash
+# Regression test for quote-render-pdf-conformance.sh.
+#
+# PostToolUse hook on browser-pdf-save. For a gated client-quote PDF whose render
+# receipt names the source HTML, it blocks when the PDF dropped links (its /URI
+# count is below the HTML's absolute-link count) or when an embedded https link
+# is not live. Everything else passes; it fails open on anything uninspectable.
+#
+# Covers (all offline-deterministic — the one network case points at a closed
+# local port so the connection refusal is immediate and reproducible):
+#   A. non-quote PDF                                  → ALLOWED (not gated)
+#   B. quote PDF, no receipt                          → ALLOWED (PreToolUse owns that block)
+#   C. quote PDF, HTML has no absolute links          → ALLOWED (0 >= 0, no fetch)
+#   D. quote PDF, PDF /URI < HTML links               → BLOCKED (link-loss, no fetch)
+#   E. quote PDF, /URI ok but an https link is dead   → BLOCKED (link not live)
+#   F. quote PDF, /URI ok and the only link is 200    → not asserted (needs a live server)
+#   G. empty stdin                                    → ALLOWED (fail-open)
+#   H. non-browser tool                               → ALLOWED (matcher defence-in-depth)
+#   I. a block emits the op=bypass fault line
+
+set -u
+
+HOOK="$(cd "$(dirname "$0")/.." && pwd)/quote-render-pdf-conformance.sh"
+if [[ ! -x "$HOOK" ]]; then
+  echo "FAIL: $HOOK not executable" >&2
+  exit 1
+fi
+
+ACCT=$(mktemp -d)
+cleanup() { rm -rf "$ACCT"; }
+trap cleanup EXIT
+
+DOCS="$ACCT/memory/users/44700900000/documents"
+mkdir -p "$DOCS"
+
+# Receipt + filed HTML for each scenario job. The receipt names the filed quote
+# HTML; the hook reads its absolute links and compares to the PDF's /URI count.
+mk_job() { # jobId, html_body, pdf_uri_repeat
+  local job="$1" body="$2" uris="$3"
+  mkdir -p "$ACCT/quoting/jobs/$job"
+  local html="$DOCS/quote-$job.html"
+  printf '%s' "$body" > "$html"
+  printf '{"jobId":"%s","filed":{"internal":"x","breakdown":"x","quote":"%s"}}' "$job" "$html" \
+    > "$ACCT/quoting/jobs/$job/render-receipt.json"
+  # A minimal PDF-ish file carrying `uris` copies of the /URI token.
+  { printf '%%PDF-1.4\n'; local i=0; while [[ $i -lt $uris ]]; do printf '/URI (x)\n'; i=$((i+1)); done; } \
+    > "$DOCS/quote-$job.pdf"
+}
+
+# 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.
+mk_job "dropped" '<html><body><a href="https://a.example/1">a</a><a href="https://b.example/2">b</a></body></html>' 0
+# E: one https link, PDF kept a /URI, but the link points at a closed local port → block on liveness.
+mk_job "dead" '<html><body><a href="https://127.0.0.1:1/never">sign</a></body></html>' 1
+
+PASS=0
+FAIL=0
+
+run_case() {
+  local name="$1" stdin="$2" expected_exit="$3" actual_exit
+  ( cd "$ACCT" && printf '%s' "$stdin" | bash "$HOOK" >/dev/null 2>/dev/null )
+  actual_exit=$?
+  if [[ "$actual_exit" -eq "$expected_exit" ]]; then
+    echo "PASS: $name (exit=$actual_exit)"; PASS=$((PASS + 1))
+  else
+    echo "FAIL: $name (expected exit=$expected_exit, got=$actual_exit)" >&2; FAIL=$((FAIL + 1))
+  fi
+}
+
+envelope() { printf '{"hook_event_name":"PostToolUse","tool_name":"%s","tool_input":{"path":"%s"}}' "$1" "$2"; }
+BROWSER="mcp__plugin_browser_browser__browser-pdf-save"
+
+run_case "A: non-quote PDF → ALLOWED" \
+  "$(envelope "$BROWSER" "$DOCS/brochure.pdf")" 0
+run_case "B: quote PDF, no receipt → ALLOWED (PreToolUse owns it)" \
+  "$(envelope "$BROWSER" "$DOCS/quote-nojob.pdf")" 0
+run_case "C: HTML has no absolute links → ALLOWED" \
+  "$(envelope "$BROWSER" "$DOCS/quote-clean.pdf")" 0
+run_case "D: PDF /URI below HTML link count → BLOCKED" \
+  "$(envelope "$BROWSER" "$DOCS/quote-dropped.pdf")" 2
+run_case "E: an embedded https link is not live → BLOCKED" \
+  "$(envelope "$BROWSER" "$DOCS/quote-dead.pdf")" 2
+run_case "G: empty stdin → ALLOWED (fail-open)" \
+  "" 0
+run_case "H: non-browser tool → ALLOWED" \
+  '{"hook_event_name":"PostToolUse","tool_name":"Write","tool_input":{"path":"'"$DOCS"'/quote-dropped.pdf"}}' 0
+
+# I: a block emits the op=bypass fault line on stderr.
+STDERR=$( cd "$ACCT" && printf '%s' "$(envelope "$BROWSER" "$DOCS/quote-dropped.pdf")" | bash "$HOOK" 2>&1 >/dev/null )
+if printf '%s' "$STDERR" | grep -q '\[quote-render\] op=bypass jobId=dropped reason=pdf-link-conformance'; then
+  echo "PASS: I: block emits op=bypass jobId=dropped"; PASS=$((PASS + 1))
+else
+  echo "FAIL: I: op=bypass line absent (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/quote-render-pdf-conformance.sh

@@ -0,0 +1,108 @@
+#!/usr/bin/env bash
+# quote-render-pdf-conformance — PostToolUse gate on browser-pdf-save.
+#
+# 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.
+#
+# 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
+#      (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
+#      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.
+#
+# 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
+# browser-pdf-save is general-purpose, so failing open here bricks no unrelated
+# PDF. No task numbers or internal refs in any operator-visible string.
+
+set -uo pipefail
+
+if [ -t 0 ]; then exit 0; fi
+INPUT=$(cat)
+[ -z "$INPUT" ] && exit 0
+
+RESULT=$(INPUT="$INPUT" BASE="$PWD" python3 - <<'PY' 2>/dev/null || true
+import os, json, re, sys, urllib.request
+
+try:
+    d = json.loads(os.environ["INPUT"])
+except Exception:
+    sys.exit(0)  # uninspectable envelope -> fail open
+
+tool = d.get("tool_name", "") or ""
+if not tool.endswith("browser-pdf-save"):
+    sys.exit(0)
+path = (d.get("tool_input", {}) or {}).get("path", "") or ""
+if not path:
+    sys.exit(0)
+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
+jobid = m.group(1)
+if "/" in jobid or ".." in jobid:
+    sys.exit(0)  # the PreToolUse gate owns bad-jobid; here fail open
+variant = m.group(2)  # "-breakdown" or None
+
+base = os.environ["BASE"]
+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
+
+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
+
+html = open(html_path, encoding="utf-8", errors="replace").read()
+# Anchors that become a /URI annotation in the printed PDF: absolute http(s) or
+# mailto hrefs. Fragment and relative anchors do not, so they are not counted.
+uri_anchors = re.findall(r'href="((?:https?|mailto):[^"]*)"', html, re.I)
+https_anchors = [u for u in uri_anchors if u.lower().startswith("https:")]
+
+# /URI occurrences in the printed PDF. This is the same primitive the e-sign
+# stamp gate uses (grep -a -c '/URI'); on real browser-pdf-save output it was
+# measured to carry one greppable /URI per surviving link (base PDFs counted 4
+# to 6, one per anchor), so the count is a faithful per-link tally, not stream-
+# compressed away. A rasterised or flattened reprint drops to a lower count.
+uri_count = open(path, "rb").read().count(b"/URI")
+if uri_count < len(uri_anchors):
+    print("BLOCK|%s|uri-count pdf=%d html_links=%d" % (jobid, uri_count, len(uri_anchors)))
+    sys.exit(0)
+
+for u in https_anchors:
+    try:
+        with urllib.request.urlopen(u, timeout=6) as r:
+            code = r.status
+    except Exception as e:
+        code = getattr(e, "code", 0) or 0
+    if code != 200:
+        print("BLOCK|%s|link %s -> %s" % (jobid, u, code))
+        sys.exit(0)
+
+sys.exit(0)
+PY
+)
+
+case "$RESULT" in
+  BLOCK\|*)
+    rest=${RESULT#BLOCK|}
+    jobid=${rest%%|*}
+    detail=${rest#*|}
+    echo "[quote-render] op=bypass jobId=$jobid reason=pdf-link-conformance detail=$detail" >&2
+    echo "Blocked: the printed quote PDF is missing links the document declared, or an embedded link is not live ($detail). Do not send it. If a Sign-Online link is not live yet, deploy the signing page first; then re-render and re-print so the PDF carries every link the document declares." >&2
+    exit 2
+    ;;
+esac
+exit 0

package/payload/platform/plugins/admin/skills/agent-builder/references/agent-pattern.md

@@ -110,12 +110,24 @@ Two further clauses bind the Output contract itself. **Recency**, universal: a t
 claim carries the date it was observed, and a date the agent cannot see is one it flags, never
 one it infers. **Corroboration**, for agents whose deliverable is a pattern, a theme, a trend, a
 signal: the agent names the independent sources behind it and does not report one as established
-on a single occurrence. Corroboration is authoring guidance enforced by review, not by the gate,
-because the subset it applies to cannot be detected statically.
-
-`agent-grounding-drift.test.ts` fails if any shipped prompt carries either sentence anything
-other than exactly once, and fails if the number of prompts it inspected is not the number it
-expects. A new agent that skips them does not ship.
+on a single occurrence.
+
+Corroboration binds only that subset, and the subset cannot be read out of a prompt's text, so
+every prompt declares it. The flat specialists carry `pattern_deliverable: true` or
+`pattern_deliverable: false` as a frontmatter key; the role `IDENTITY.md` files, which have no
+frontmatter and are injected raw, carry the same marker as a trailing HTML comment
+`<!-- pattern_deliverable: true -->`. Absent is a gate failure, not a default. A prompt declaring
+true carries this sentence, character for character, as a third paragraph of its `## Grounding`
+section; a prompt declaring false does not carry it at all:
+
+> Where what you report is a pattern, a theme, a trend, or a signal, name the independent occurrences behind it; one occurrence is a single observation you report as such, never a pattern you assert.
+
+`agent-grounding-drift.test.ts` fails if any shipped prompt carries the provenance or
+person-attribute sentence anything other than exactly once, if a prompt does not declare
+`pattern_deliverable` exactly once, if a true-declaring prompt carries the corroboration sentence
+anything other than exactly once, if a false-declaring prompt carries it at all, and if the
+number of prompts it inspected is not the number it expects. The marker and the sentence cannot
+drift apart, and a new agent that skips any of the three does not ship.
 
 ## Skills owned
 

package/payload/platform/plugins/business-assistant/skills/e-sign/SKILL.md

@@ -477,7 +477,15 @@ Dispatch runs **only** inside a live operator session on the account's own devic
 
 2. **For each unswept row, in order — stamp, send, then mark that one row swept:**
 
-   - **Stamp a per-signer copy from the persisted base — no browser, no network.** Dispatch must **never fetch the deployed page**: it may sit behind **Cloudflare Access**, so a headless fetch hits the Access login screen, not the document, and the PDF is garbage. The render-once base (§ 5) is what removes that dependency. Load `${ACCOUNT_DIR}/e-sign/<DOC_REF>/base.pdf`, append an **Electronic Acceptance Certificate** page, and write a per-signer copy alongside it — all with a pure PDF library (**`pdf-lib`**, run as a small Node script; pick another pure library if the account standardises on one, but it must add no browser and no network call):
+   - **Stamp a per-signer copy from the persisted base — no browser, no network.** Dispatch must **never fetch the deployed page**: it may sit behind **Cloudflare Access**, so a headless fetch hits the Access login screen, not the document, and the PDF is garbage. The render-once base (§ 5) is what removes that dependency. Load `${ACCOUNT_DIR}/e-sign/<DOC_REF>/base.pdf`, append an **Electronic Acceptance Certificate** page, and write a per-signer copy alongside it, all with a PDF library that loads the base and copies its pages through intact (**`pdf-lib`**, run as a small Node script). The stamp copies existing pages; it never renders them to an image. Rasterising the base (ghostscript to PNG, or any image-then-redraw rebuild) discards every link annotation and all selectable text, so the signer receives a flattened copy with dead links; it is prohibited whatever is or is not installed. A substitute for pdf-lib is allowed only if it imports existing PDF pages: pypdf, qpdf, or pdftk. A canvas-only generator such as reportlab cannot import a base and is not a substitute. Whatever the library, it adds no browser and no network call.
+
+     **Pre-flight: the page-copying library must resolve before any stamp runs.** A stamp attempted without it is the exact history this guards against, where a prior session met the missing library by rasterising instead of installing one:
+
+     ```bash
+     node -e 'import("pdf-lib").then(()=>console.log("ok"),e=>{console.error("pdf-lib missing: npm i pdf-lib at the account directory root");process.exit(1)})'
+     ```
+
+     On failure the one remediation is that install; a fallback that renders pages to images is never one. The stamp script itself:
 
      ```js
      // stamp.mjs — node, offline. Reads the persisted base, appends a certificate page,
@@ -509,6 +517,8 @@ Dispatch runs **only** inside a live operator session on the account's own devic
 
      The certificate fields come **from the D1 row**, not a re-fetch: `name`, `title` (an operator-defined field if present), `token`, `doc_ref`, `accepted_at`, the signing `method`, and the **verbatim intent/consent assertion** the signer ticked (§ 2). That makes the artifact self-contained evidence of who accepted, when, and on what stated basis.
 
+     **Post-stamp gate: prove fidelity before any send.** For both `base.pdf` and the stamped copy, count link annotations with `grep -a -c '/URI'` and measure page-1 text extent with ghostscript text extraction (`gs -q -dNOPAUSE -dBATCH -sDEVICE=txtwrite -dFirstPage=1 -dLastPage=1 -o - <file> | wc -c`). The stamped copy passes only when its `/URI` count and its page-1 text extent are each at least the base's. On either regression the stamp rasterised or otherwise flattened the base, so delete the stamped copy, skip both sends, and leave the row `swept = 0` so the next sweep re-surfaces it. This gate converts a link-stripped copy from a no-event failure (nothing logs until a signer clicks a dead link) into a rejection at stamp time. Record the base and stamped `/URI` counts alongside every dispatch, pass or fail, so a fidelity regression is a number rather than a complaint.
+
    - **Send twice via `email-send`**, each carrying `doc_ref`, `name`, `token`, `accepted_at`, and the **stamped** PDF (`signed-<token>.pdf`) as an attachment:
      - once to the **business owner's configured address** (read from configured business identity — never hard-code a recipient in this workflow);
      - once to the **signer's captured `email`** — this copy is the **statutory record provided to the signer**, the evidentiary copy the legal basis (intro) relies on.

package/payload/platform/plugins/cloudflare/bin/__tests__/portal-brand-css.test.sh

@@ -18,7 +18,7 @@ set -u
 
 BIN_DIR="$(cd "$(dirname "$0")/.." && pwd)"
 SCRIPT="$BIN_DIR/portal-brand-css.mjs"
-TEMPLATE="$BIN_DIR/../skills/data-portal/template/public/portal.css"
+TEMPLATE="$BIN_DIR/../skills/data-portal/template/portal.css"
 [ -f "$SCRIPT" ] || { echo "FAIL: $SCRIPT not found" >&2; exit 1; }
 [ -f "$TEMPLATE" ] || { echo "FAIL: $TEMPLATE not found" >&2; exit 1; }
 # Case 2 strips the :root block with perl and diffs what is left. Without perl

package/payload/platform/plugins/cloudflare/bin/portal-index-push.mjs

@@ -198,6 +198,28 @@ export async function pushAccount(opts) {
   const current = Number(state[0]?.currentGeneration ?? 0)
   const next = current + 1
 
+  // Crash safety (Task 1923). A stage that died mid-batch — a D1 500 on one
+  // INSERT — leaves rows at `next` while the pointer stays at `current`. Every
+  // later run recomputes the same `next`, and its first colliding INSERT then
+  // hits UNIQUE(accountId, relPath, generation), so the index freezes at the
+  // stale generation until an operator hand-clears the orphans. Clearing `next`
+  // before staging lets a partial stage self-heal on the next cycle. Guarded on
+  // a non-zero count so the DELETE never precedes the flip on a clean cycle and
+  // the log line always means a recovered wedge. The count comes from a SELECT
+  // because the D1 client returns rows, not the affected-row meta.
+  const orphan = await client.query(
+    'SELECT COUNT(*) AS n FROM directory WHERE accountId = ? AND generation = ?',
+    [accountId, next],
+  )
+  const orphanCount = Number(orphan[0]?.n ?? 0)
+  if (orphanCount > 0) {
+    await client.query('DELETE FROM directory WHERE accountId = ? AND generation = ?', [
+      accountId,
+      next,
+    ])
+    log(`${TAG} op=stage-clear account=${accountId} generation=${next} cleared=${orphanCount}`)
+  }
+
   for (const row of rows) {
     await client.query(
       'INSERT INTO directory (accountId, relPath, sizeBytes, modifiedAt, indexedAt, isDir, generation) ' +

package/payload/platform/plugins/cloudflare/mcp/__tests__/portal-index-push.test.ts

@@ -309,13 +309,85 @@ function generationClient() {
         return []
       }
       if (/DELETE FROM directory\b/i.test(sql)) {
-        const keep = Number(params[1])
-        for (let i = rows.length - 1; i >= 0; i--) {
-          if (rows[i].generation !== keep) rows.splice(i, 1)
+        const g = Number(params[1])
+        // Two DELETE shapes reach this client: the post-flip sweep removes
+        // every OTHER generation (`generation != ?`); the pre-stage clear
+        // (Task 1923) removes exactly THIS generation (`generation = ?`).
+        if (/generation\s*!=\s*\?/i.test(sql)) {
+          for (let i = rows.length - 1; i >= 0; i--) if (rows[i].generation !== g) rows.splice(i, 1)
+        } else {
+          for (let i = rows.length - 1; i >= 0; i--) if (rows[i].generation === g) rows.splice(i, 1)
         }
         return []
       }
       if (/SELECT COUNT/i.test(sql)) {
+        // The pre-stage orphan count (Task 1923) filters `generation = ?`; the
+        // verify count joins the pointer. Only the former binds a generation.
+        if (/generation\s*=\s*\?/i.test(sql)) {
+          const g = Number(params[1])
+          return [{ n: rows.filter((r) => r.generation === g).length }]
+        }
+        return [{ n: rows.filter((r) => r.generation === pointer).length }]
+      }
+      return []
+    },
+  }
+}
+
+// The wedge Task 1923 fixes: a stage that half-completed on a D1 500 leaves
+// orphan rows at the NEXT generation while the pointer stays at current. This
+// client models the one property that turns that into a permanent freeze — the
+// D1 UNIQUE(accountId, relPath, generation) constraint — by throwing on a
+// colliding INSERT, exactly as every later cycle's first re-stage did.
+function wedgeableClient(seed: { pointer: number; current?: string[]; orphans: string[] }) {
+  const calls: { sql: string; params: unknown[] }[] = []
+  const rows: { accountId: string; relPath: string; generation: number }[] = []
+  let pointer: number | null = seed.pointer
+  const orphanGen = seed.pointer + 1
+  // The last good tree the pointer names, present in a real wedge alongside the
+  // orphans. Seeding it proves the pre-stage clear scopes to `next` and leaves
+  // the reader-visible current generation untouched.
+  for (const relPath of seed.current ?? []) rows.push({ accountId: 'acc-1', relPath, generation: seed.pointer })
+  for (const relPath of seed.orphans) rows.push({ accountId: 'acc-1', relPath, generation: orphanGen })
+  return {
+    calls,
+    rows,
+    pointerValue: () => pointer,
+    async query(sql: string, params: unknown[] = []) {
+      calls.push({ sql, params })
+      if (/SELECT\s+currentGeneration/i.test(sql)) {
+        return pointer === null ? [] : [{ currentGeneration: pointer }]
+      }
+      if (/INSERT INTO directory_state|UPDATE directory_state/i.test(sql)) {
+        pointer = Number(params[1] ?? params[0])
+        return []
+      }
+      if (/INSERT INTO directory \(/i.test(sql)) {
+        const accountId = String(params[0])
+        const relPath = String(params[1])
+        const generation = Number(params[6])
+        if (rows.some((r) => r.accountId === accountId && r.relPath === relPath && r.generation === generation)) {
+          throw new Error(
+            'd1 query failed: HTTP 500 — UNIQUE constraint failed: directory.accountId, directory.relPath, directory.generation',
+          )
+        }
+        rows.push({ accountId, relPath, generation })
+        return []
+      }
+      if (/DELETE FROM directory\b/i.test(sql)) {
+        const g = Number(params[1])
+        if (/generation\s*!=\s*\?/i.test(sql)) {
+          for (let i = rows.length - 1; i >= 0; i--) if (rows[i].generation !== g) rows.splice(i, 1)
+        } else {
+          for (let i = rows.length - 1; i >= 0; i--) if (rows[i].generation === g) rows.splice(i, 1)
+        }
+        return []
+      }
+      if (/SELECT COUNT/i.test(sql)) {
+        if (/generation\s*=\s*\?/i.test(sql)) {
+          const g = Number(params[1])
+          return [{ n: rows.filter((r) => r.generation === g).length }]
+        }
         return [{ n: rows.filter((r) => r.generation === pointer).length }]
       }
       return []
@@ -323,6 +395,42 @@ function generationClient() {
   }
 }
 
+describe('a partial stage self-heals (Task 1923)', () => {
+  it('clears orphans at the next generation, flips onto it, and logs stage-clear', async () => {
+    // Pointer at 5 naming the last good tree; three orphan rows already at
+    // generation 6 for relPaths the current walk re-stages ('output' is the
+    // walk's first row, so the current code's first INSERT is the one that
+    // collides). Without the pre-stage clear that INSERT throws on the UNIQUE
+    // constraint and the push fails, which is what froze gls-data for ~6 h on
+    // 2026-07-22.
+    const c = wedgeableClient({
+      pointer: 5,
+      current: ['output', 'output/report.pdf', 'quotes', 'quotes/CR2969'],
+      orphans: ['output', 'output/report.pdf', 'quotes'],
+    })
+    const lines: string[] = []
+    const r = await push(c, { log: (l: string) => lines.push(l) })
+
+    expect(r.rows).toBe(7)
+    expect(c.pointerValue()).toBe(6)
+    // Nothing survives at a generation the pointer does not name.
+    expect(c.rows.every((row) => row.generation === 6)).toBe(true)
+    const clear = lines.find((l) => l.includes('op=stage-clear'))!
+    expect(clear).toContain('account=acc-1')
+    expect(clear).toContain('generation=6')
+    // Exactly the 3 orphans at generation 6, not the 4 current-tree rows the
+    // pointer names: the clear scopes to `next`, never to a reader-visible row.
+    expect(clear).toContain('cleared=3')
+  })
+
+  it('emits no stage-clear line on a clean cycle with no orphans', async () => {
+    const c = wedgeableClient({ pointer: 5, orphans: [] })
+    const lines: string[] = []
+    await push(c, { log: (l: string) => lines.push(l) })
+    expect(lines.some((l) => l.includes('op=stage-clear'))).toBe(false)
+  })
+})
+
 describe('the index replace is atomic', () => {
   it('never issues a delete before the pointer flip', async () => {
     // The delete-then-insert window this replaces was Task 1842: a client

package/payload/platform/plugins/cloudflare/mcp/__tests__/portal-indexed-download.test.ts

@@ -60,6 +60,7 @@ const deadHead = async () => {
   throw new Error('ECONNREFUSED')
 }
 const errHead = async () => ({ ok: false, status: 502 })
+const missingHead = async () => ({ ok: false, status: 404 })
 
 describe('processIndexedDownload', () => {
   it('returns a signed url for an indexed file when the device answers', async () => {
@@ -87,6 +88,18 @@ describe('processIndexedDownload', () => {
     expect(r.payload.error).toBe('device-offline')
   })
 
+  // A live device that answers 404 means the indexed row is stale: the file was
+  // renamed or removed while the index was frozen. That is "refresh the list",
+  // not "the device is down", so it must not collapse into device-offline.
+  it('reports file-missing when a reachable device 404s the path', async () => {
+    const lines: string[] = []
+    const r = await processIndexedDownload('sess-a', PATH, makeEnv(), (l) => lines.push(l), 1000, missingHead as never)
+    expect(r.status).toBe(404)
+    expect(r.payload.error).toBe('file-missing')
+    expect(r.url).toBeUndefined()
+    expect(lines.some((l) => l.includes('result=file-missing'))).toBe(true)
+  })
+
   it('404s a path that is not in the index, without contacting the device', async () => {
     let touched = false
     const spy = async () => {

package/payload/platform/plugins/cloudflare/skills/data-portal/template/functions/api/download.ts

@@ -171,6 +171,18 @@ export async function processIndexedDownload(
   try {
     const head = await fetchFn(url, { method: 'HEAD' })
     if (!head.ok) {
+      if (head.status === 404) {
+        // The device answered, so it is not down: this row is stale. The file
+        // was renamed or removed while the index was frozen, and the device
+        // returns the same 404 for a path that is missing and one that is not
+        // exposed — so this cannot and must not try to tell those apart. The
+        // client's remedy is "refresh the list", not "wait for the device".
+        log(
+          `[data-portal] op=fetch-through owner=${q(session.ownerId)} path=${q(relPath)} ` +
+            `status=404 ms=${Date.now() - started} result=file-missing`,
+        )
+        return { status: 404, payload: { ok: false, error: 'file-missing' } }
+      }
       log(
         `[data-portal] op=fetch-through owner=${q(session.ownerId)} path=${q(relPath)} ` +
           `status=${head.status} ms=${Date.now() - started} result=device-error`,

package/payload/platform/plugins/cloudflare/skills/data-portal/template/portal.js

@@ -292,6 +292,14 @@
           say('That file is on the device, which is not reachable right now. Try again shortly.');
           return;
         }
+        /* A reachable device that 404s a stale row sends error:'file-missing'.
+           The message says refresh, not wait. Keyed on the string, so the
+           edge's own not-found 404s (not-granted, absent, is-directory) carry
+           error:'not found' and keep the generic message below. */
+        if (res.d && res.d.error === 'file-missing') {
+          say('That file is no longer available under this name. Refresh the list and try again.');
+          return;
+        }
         if (!res.d.ok || !res.d.url) {
           say('That file could not be opened.');
           return;

package/payload/platform/scripts/lib/provision-account-dir.sh

@@ -128,6 +128,12 @@ provision_account_dir() {
           { "type": "command", "command": "bash $HOOKS_PATH/post-tool-use-agent.sh" }
         ]
       },
+      {
+        "matcher": "mcp__plugin_browser_browser__browser-pdf-save",
+        "hooks": [
+          { "type": "command", "command": "bash $HOOKS_PATH/quote-render-pdf-conformance.sh" }
+        ]
+      },
       {
         "matcher": "mcp__.*__.*-(export|import)-parse$",
         "hooks": [

package/payload/platform/services/claude-session-manager/dist/http-server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http-server.d.ts","sourceRoot":"","sources":["../src/http-server.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"http-server.d.ts","sourceRoot":"","sources":["../src/http-server.ts"],"names":[],"mappings":"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"}

package/payload/platform/services/claude-session-manager/dist/http-server.js

@@ -2071,6 +2071,10 @@ export function buildHttpApp(deps) {
         }
         const byte = body.byte;
         const trigger = typeof body.trigger === 'string' ? body.trigger : 'manual';
+        // Task 1920 — the stop button sets escalate:true so that when ESC proves
+        // ineffective (turn blocked in a tool/subagent call) the manager escalates
+        // once to Ctrl-C. Absent/false keeps the ESC-only re-send path.
+        const escalate = body.escalate === true;
         const intId = `${sessionId.slice(0, 8)}-${start}`;
         deps.logger(`[webchat-interrupt] op=interrupt-requested intId=${intId} sessionId=${sessionId.slice(0, 8)} trigger=${trigger}`);
         const result = writeInterruptToPty(sessionId, byte, deps.logger);
@@ -2115,6 +2119,11 @@ export function buildHttpApp(deps) {
         let lastSendAt = sentAt;
         let escSends = 1; // the initial ESC already written above
         let canResend = true;
+        // Task 1920 — the one-shot escalation guard. Seed it from the initial byte:
+        // if the pre-loop write above already sent Ctrl-C (byte='ctrl-c'), the loop
+        // must not send a second one. The invariant is "exactly one Ctrl-C ever per
+        // call" because a second SIGINT can exit the CLI and kill the session.
+        let ctrlCSent = byte === 'ctrl-c';
         while (Date.now() - sentAt < stopMs) {
             const st = deps.watcher.getBySessionId(sessionId)?.status;
             if (st !== 'busy') {
@@ -2122,14 +2131,34 @@ export function buildHttpApp(deps) {
                 break;
             }
             if (canResend && Date.now() - lastSendAt >= reescalateMs) {
-                const re = writeInterruptToPty(sessionId, byte, deps.logger);
-                lastSendAt = Date.now();
-                if (re.ok) {
-                    escSends += 1;
-                    deps.logger(`[webchat-interrupt] op=interrupt-reescalated intId=${intId} sends=${escSends}`);
+                if (escalate) {
+                    // Task 1920 — ESC ran for a full sub-window while still busy, so it is
+                    // ineffective (turn blocked in a tool/subagent call). Escalate once to
+                    // Ctrl-C (SIGINT reaches the harness mid-tool-call); never a second
+                    // time — a second SIGINT can exit the CLI and kill the session. After
+                    // the one Ctrl-C, stop sending and just poll for busy-clear.
+                    if (!ctrlCSent) {
+                        const esc = writeInterruptToPty(sessionId, 'ctrl-c', deps.logger);
+                        lastSendAt = Date.now();
+                        if (esc.ok) {
+                            ctrlCSent = true;
+                            deps.logger(`[webchat-interrupt] op=interrupt-escalated intId=${intId} mechanism=ctrl-c sends=${escSends + 1}`);
+                        }
+                        else {
+                            canResend = false; // child vanished mid-interrupt; the next status read exits the loop
+                        }
+                    }
                 }
                 else {
-                    canResend = false; // child vanished mid-interrupt; the next status read exits the loop
+                    const re = writeInterruptToPty(sessionId, byte, deps.logger);
+                    lastSendAt = Date.now();
+                    if (re.ok) {
+                        escSends += 1;
+                        deps.logger(`[webchat-interrupt] op=interrupt-reescalated intId=${intId} sends=${escSends}`);
+                    }
+                    else {
+                        canResend = false; // child vanished mid-interrupt; the next status read exits the loop
+                    }
                 }
             }
             await new Promise((r) => setTimeout(r, 120));