@rubytech/create-maxy-code 0.1.567 → 0.1.569

package/dist/__tests__/brand-agent-root.test.js

@@ -0,0 +1,91 @@
+// Task 2460 — the brand root is no longer a registration surface. It was
+// written once at install and never pruned, so a retired template stayed
+// registered forever: clare-craig carries `archive-ingest-operator.md` as a
+// dangling symlink into a template that no longer exists, and Task 2416 had to
+// strip its roster line by hand on five installs while the link survived.
+// Ceasing to write it is not enough, because every existing install already
+// carries the links.
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, symlinkSync, readdirSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { clearBrandAgentRoot } from "../brand-agent-root.js";
+/** A temp brand root with an empty `agents/` under it, plus a collector for the
+ *  one line the function emits. */
+function makeRoot() {
+    const root = mkdtempSync(join(tmpdir(), "t2460-brand-root-"));
+    const agentsDir = join(root, "agents");
+    mkdirSync(agentsDir, { recursive: true });
+    const lines = [];
+    return { root, agentsDir, lines, log: (l) => lines.push(l) };
+}
+test("removes every markdown symlink and counts them", () => {
+    const { root, agentsDir, lines, log } = makeRoot();
+    try {
+        const target = join(root, "database-operator.md");
+        writeFileSync(target, "---\n");
+        symlinkSync(target, join(agentsDir, "database-operator.md"));
+        // The dangling case, which is what clare-craig actually carries.
+        symlinkSync(join(root, "gone.md"), join(agentsDir, "archive-ingest-operator.md"));
+        const result = clearBrandAgentRoot(agentsDir, log);
+        assert.deepEqual(result, { removed: 2, kept: [] });
+        assert.deepEqual(readdirSync(agentsDir), []);
+        // The link goes, never the template it pointed at.
+        assert.ok(existsSync(target));
+        assert.deepEqual(lines, ["  [brand-agent-root] op=brand-agent-root-cleared removed=2 kept="]);
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});
+test("keeps a regular file and names it", () => {
+    const { root, agentsDir, lines, log } = makeRoot();
+    try {
+        writeFileSync(join(agentsDir, "hand-written.md"), "---\n");
+        const result = clearBrandAgentRoot(agentsDir, log);
+        assert.deepEqual(result, { removed: 0, kept: ["hand-written.md"] });
+        assert.ok(existsSync(join(agentsDir, "hand-written.md")));
+        assert.deepEqual(lines, ["  [brand-agent-root] op=brand-agent-root-cleared removed=0 kept=hand-written.md"]);
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});
+test("leaves non-markdown entries alone", () => {
+    const { root, agentsDir, log } = makeRoot();
+    try {
+        writeFileSync(join(agentsDir, "notes.txt"), "scratch");
+        assert.deepEqual(clearBrandAgentRoot(agentsDir, log), { removed: 0, kept: [] });
+        assert.ok(existsSync(join(agentsDir, "notes.txt")));
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});
+test("reports removed=0 on a directory that does not exist", () => {
+    const { root, agentsDir, lines, log } = makeRoot();
+    try {
+        rmSync(agentsDir, { recursive: true, force: true });
+        assert.deepEqual(clearBrandAgentRoot(agentsDir, log), { removed: 0, kept: [] });
+        assert.deepEqual(lines, ["  [brand-agent-root] op=brand-agent-root-cleared removed=0 kept="]);
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});
+test("is idempotent: a second run reports removed=0", () => {
+    const { root, agentsDir, lines, log } = makeRoot();
+    try {
+        const target = join(root, "database-operator.md");
+        writeFileSync(target, "---\n");
+        symlinkSync(target, join(agentsDir, "database-operator.md"));
+        clearBrandAgentRoot(agentsDir, log);
+        lines.length = 0;
+        assert.deepEqual(clearBrandAgentRoot(agentsDir, log), { removed: 0, kept: [] });
+        assert.deepEqual(lines, ["  [brand-agent-root] op=brand-agent-root-cleared removed=0 kept="]);
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});

package/dist/brand-agent-root.js

@@ -0,0 +1,58 @@
+// Task 2460 — the brand-wide agent root is retired.
+//
+// `$CLAUDE_CONFIG_DIR/agents/` was written once, by the installer, from
+// `platform/templates/specialists/agents/`, and never pruned. Three things
+// followed. A retired template stayed registered forever: on clare-craig,
+// `archive-ingest-operator.md` is a dangling symlink into a template that no
+// longer exists, and Task 2416 had to strip its roster line by hand on five
+// installs while the link survived. A specialist disabled on one account stayed
+// resolvable by name in that account and in every other account on the install,
+// because disabling touches only `<accountDir>/specialists/agents/`. And an
+// authored specialist could never be registered here at all without becoming
+// dispatchable inside every other account on the box.
+//
+// The replacement is one registry per account, mirrored at spawn by
+// `syncAccountAgentRegistry`. Dispatch is unaffected by emptying this root:
+// provisioning copies every template specialist into each account's
+// `specialists/agents/`, which that registry mirrors, and cwd at every spawn is
+// the account whose source is mirrored.
+//
+// This function removes what the old surface left behind. Removal rather than
+// merely ceasing to write, because every existing install already carries the
+// links.
+import { existsSync, lstatSync, readdirSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+/** Remove every `*.md` symlink under `agentsDir`. A regular file is the
+ *  operator's own and is kept and named, never deleted. Returns the counts and
+ *  logs `op=brand-agent-root-cleared removed=<N> kept=<names>` once, which is
+ *  the per-box record the fleet remediation is tracked against. */
+export function clearBrandAgentRoot(agentsDir, log = () => { }) {
+    let removed = 0;
+    const kept = [];
+    // A missing directory is an install that never had the old surface. Nothing
+    // to clear is a real result, not an error, so it still logs its zero.
+    if (existsSync(agentsDir)) {
+        for (const entry of readdirSync(agentsDir).sort()) {
+            if (!entry.endsWith(".md"))
+                continue;
+            const path = join(agentsDir, entry);
+            let stat;
+            try {
+                // lstat, not stat: the links this clears are frequently dangling, which
+                // is the whole of symptom 2, and stat would throw on exactly those.
+                stat = lstatSync(path);
+            }
+            catch {
+                continue;
+            }
+            if (!stat.isSymbolicLink()) {
+                kept.push(entry);
+                continue;
+            }
+            unlinkSync(path);
+            removed++;
+        }
+    }
+    log(`  [brand-agent-root] op=brand-agent-root-cleared removed=${removed} kept=${kept.join(",")}`);
+    return { removed, kept };
+}

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { execFileSync, spawn, spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, writeFileSync, cpSync, readFileSync, rmSync, readdirSync, appendFileSync, openSync, closeSync, chmodSync, statSync, realpathSync, accessSync, constants as fsConstants } from "node:fs";
-import { registerSpecialistAgentsAt, SpecialistSymlinkCollision } from "./specialist-registration.js";
+import { clearBrandAgentRoot } from "./brand-agent-root.js";
 import { seedBypassPermissionsSettings, assertBypassPermissionsSeed } from "./permissions-seed.js";
 import { resolve, join, dirname } from "node:path";
 import { randomBytes } from "node:crypto";
@@ -3419,14 +3419,13 @@ function setupAccount() {
             env: { ...neo4jEnv, PLATFORM_ROOT: join(INSTALL_DIR, "platform") },
         });
     }
-    // Task 165 — register every bundled specialist subagent at
-    // $CLAUDE_CONFIG_DIR/agents/<name>.md. Claude Code's `--agent <name>`
-    // discovery only resolves under this path; without these symlinks,
-    // every `--agent database-operator` etc. silently runs as the admin
-    // agent on admin IDENTITY/SOUL scaffolding. Symlinks (not copies) so
-    // a `npx -y @rubytech/create-maxy-code` upgrade picks up template
-    // changes without a second seed run.
-    registerSpecialistAgents();
+    // Task 2460 — clear the brand-wide agent root this step used to write.
+    // Every bundled specialist now reaches a session through the per-account
+    // registry that `syncAccountAgentRegistry` mirrors at spawn from
+    // `<accountDir>/specialists/agents/`, which provisioning fills from the same
+    // templates. Runs on every install, so an upgrade removes the links an
+    // earlier install left behind.
+    clearBrandAgentRegistrations();
     // install-time defaults. Stamp `account.json` with the
     // brand's default plugin set + default outputStyle / thinkingView, and
     // write a minimal admin SOUL.md. The agent boots into a working state
@@ -3595,25 +3594,23 @@ function writeEntitlementFromFlag(payload) {
     console.log(line);
     logFile(line);
 }
-// Task 394 — premium-bundle agents register through the native Claude Code
-// subagent registry via `.claude-plugin/plugin.json` manifests emitted by
-// scripts/generate-plugin-manifests.mjs at bundle time, not through a
-// parallel symlink channel. This function still wires the bundled platform
-// specialists (database-operator, project-manager, …) under
-// platform/templates/specialists/agents/, which are not part of a
-// registered plugin and rely on $CLAUDE_CONFIG_DIR/agents/ resolution.
-function registerSpecialistAgents() {
-    try {
-        registerSpecialistAgentsAt(join(INSTALL_DIR, "platform/templates/specialists/agents"), join(CLAUDE_CONFIG_DIR, "agents"), (line) => { console.log(line); logFile(line); });
-    }
-    catch (err) {
-        if (err instanceof SpecialistSymlinkCollision) {
-            console.error(`Setup failed: ${err.message}`);
-            console.error(`  Remove the file and re-run.`);
-            process.exit(1);
-        }
-        throw err;
-    }
+// Task 2460 — the brand root is no longer a registration surface. It was
+// written once and never pruned, which left retired templates registered
+// forever and left a specialist disabled on one account dispatchable in every
+// other account on the install. Bundled platform specialists reach a session
+// through the per-account registry instead; this step removes the links the old
+// surface left behind, which is what closes those two symptoms on an existing
+// install rather than only on a fresh one.
+//
+// Task 394 — premium-bundle agents were never registered here. They resolve
+// through the native Claude Code subagent registry via `.claude-plugin/plugin.json`
+// manifests emitted by scripts/generate-plugin-manifests.mjs at bundle time, so
+// clearing this directory does not touch them.
+function clearBrandAgentRegistrations() {
+    clearBrandAgentRoot(join(CLAUDE_CONFIG_DIR, "agents"), (line) => {
+        console.log(line);
+        logFile(line);
+    });
 }
 // ---------------------------------------------------------------------------
 // Account discovery (shared by installService + the post-install summary)

package/package.json

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

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

@@ -268,10 +268,12 @@ 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-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. **Scope** is three path shapes, all resolved against the account dir: `memory/users/<phone>/documents/quote-<jobId>[-breakdown].pdf`, `jobs/<jobId>/quote/<anything>.pdf`, and `jobs/<jobId>/Quotations/<anything>.pdf`. `jobs/<jobId>/pricing/` is excluded — it holds the internal priced breakdown, excluded with the admin-scope internal view. **Decision** is receipt *identity*, not receipt existence: the gate resolves the PDF's sibling HTML (`.pdf`→`.html`), sha256s it, and requires a match against the sha256 of a file named by `filed.quote` or `filed.breakdown` in `quoting/jobs/<jobId>/render-receipt.json`. `filed.internal` is not client-facing and never matches. Comparing content rather than paths keeps an operator copy of a rendered document passing while hand-authored content fails. A missing sibling HTML blocks: the pipeline files the PDF beside the HTML it printed from, so no local source is no proof of renderer origin. Existence alone was not enough — on the 2026-08-05 bypass the job's figures were rewritten after the render and the delivered document was written later still, so a stale receipt would have authorised the print. **Log line** (stderr, on a block): `[quote-render] op=bypass jobId=<jobId> reason=<not-receipt-filed|no-source-html|bad-jobid>`. Every non-quote PDF — brochures, works orders, invoices, the admin-scope internal view — passes 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-engine-gate.sh` — **PreToolUse matcher=`Bash`** (a third command on the same `Bash` matcher as `archive-ingest-surface-gate` and `fs-schema-guard-bash-pre`, any exit 2 blocks). Makes the deterministic `quote-engine-run` / `quote-render` tools the only route the account's persisted quoting scripts can run. Blocks (exit 2) a `Bash` `command` that executes `quoting/engine.mjs` or `quoting/render.mjs` directly — the pricing and render scripts must run through their MCP tools, which apply the reconcile / margin-leak / link-liveness gates and write the figures and render receipts. A hand-run `node quoting/engine.mjs` (the SiteDesk 2026-07-25 bypass: a repricing dispatched to content-producer that ran the engine by hand and re-rendered off the deterministic path) skips all of that, so it is refused. It fires only on an execution (a JS runtime invoking the script, or the script run at command position); a read or inspect of the file (`cat`/`grep`/`git diff quoting/engine.mjs`) and every unrelated `Bash` command pass at exit 0. A `mode=verify` reproduction is gated too — it must also run through `quote-engine-run`, so a hand-run `node quoting/engine.mjs mode=verify` is refused. Known fail-open gap (accepted, consistent with the soft posture): a `cd quoting && node engine.mjs` drops the `quoting/` prefix and is not matched. **Block message:** `Blocked: the quoting engine and render scripts must run through their tools, not directly. Use the quote-engine-run tool to price a job (it files the figures) and the quote-render tool to produce the documents (it files them behind the reconcile, margin-leak and link-liveness gates). Running quoting/engine.mjs or quoting/render.mjs by hand skips those gates and files no receipt.` **Log line** (stderr, on a block): `[quote-engine] op=bypass reason=direct-script-exec`. **Fail-open** on an uninspectable call (tty / empty stdin / no `python3`): `Bash` is a general-purpose tool and the agent never controls this hook's stdin, so failing open opens no bypass while never bricking unrelated commands.
+- `hooks/quote-pdf-bash-gate.sh` — **PreToolUse matcher=`Bash`.** Closes the Bash route to a client quote PDF. `quote-render-gate` refuses a hand-authored quote at `browser-pdf-save`, but an agent holding `Bash` reaches the same outcome with any HTML-to-PDF converter and meets no control at all (`content-producer` holds `Bash`, `Write`, `Edit` and `browser-pdf-save`; `quote-engine-gate` refuses only execution of the two persisted quoting scripts). Blocks (exit 2) a command that names both an `.html` under a gated quote path — `memory/users/<phone>/documents/`, `jobs/<jobId>/quote/`, `jobs/<jobId>/Quotations/` — and a `.pdf`. The match is structural on the paths, never on the converter's name, so `wkhtmltopdf`, `chromium --print-to-pdf` and `weasyprint` are covered by the same rule. A read that names no PDF (`cat q.html`) passes, and `jobs/<jobId>/pricing/` is never gated. **Block message:** `Blocked: a client quote PDF must come from the quote-render tool, not from a converter run by hand. Run quote-render for this job — it files the document and its render receipt — then print the client HTML path it returns.` **Log line** (stderr, on a block): `[quote-render] op=bypass reason=bash-pdf-production`. **Fail-open** on an uninspectable call.
+- `hooks/quote-path-write-gate.sh` — **PreToolUse matcher=`Write` / `Edit` / `MultiEdit` / `NotebookEdit`.** The roster safeguard expressed as a capability rather than a removal. Blocks (exit 2) a write whose target is under `jobs/<jobId>/quote/`, `jobs/<jobId>/Quotations/` or `quoting/templates/` when the calling agent's card does not grant `quote-render`. `jobs/<jobId>/pricing/` is excluded — the internal priced breakdown is not a client quote artefact — and every other deliverable the agent owns (works orders, heritage statements, survey sheets, drawing registers, trial-pit records, invoice stamps) is untouched. **Caller identity is `agent_type` from the hook envelope**, which Claude Code sets when a hook fires inside a subagent; `MAXY_SPECIALIST` is not usable, since it is stamped only when a specialist is spawned as its own PTY process and reads empty for the native Agent-tool subagents this gate exists to stop. **Card lookup spans both registration families** — the per-account registry (`<accountDir>/.claude/agents/`, `<accountDir>/specialists/agents/`), `$CLAUDE_CONFIG_DIR/agents/`, and the plugin roots (`$(dirname $PLATFORM_ROOT)/premium-plugins/*/agents/`, `$PLATFORM_ROOT/plugins/*/agents/`) — matching on frontmatter `name:` as well as filename, because the quoter's card is filed as `sitedesk--quoter.md` and declares `name: quoter`. Omitting the premium root would block the quoter itself. A write from the main conversation carries no `agent_type` and the admin seat holds no `quote-render`, so it is refused too: no part of a client quote document is another agent's work, the admin's included. **Block message:** `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.` **Log line** (stderr, on a block): `[quote-render] op=bypass reason=<quote-path-write-without-render-tool|quote-path-write-unresolved-agent>`. **Fail-open** on an uninspectable envelope.
 - `hooks/preference-consult-gate.sh` — **PreToolUse gate on customer-facing document deliverables.** Registered against `mcp__plugin_browser_browser__browser-pdf-save` (a second command on the same matcher as `quote-render-gate`, either exit 2 blocks) and against the email/Outlook send tools plus `SendUserFile`. It fires only in the document-deliverable shape: a `browser-pdf-save` or `SendUserFile` whose path is under `memory/users/<phone>/documents/` (or a `SendUserFile` of a `.pdf`/`.html`/`.docx`), and `email-send`/`email-reply`/`email-draft-send`/`outlook-mail-send`/`outlook-mail-reply`/`outlook-draft-send` carrying a non-empty `attachments`. For a gated call it reads the session transcript (`transcript_path`) and blocks (exit 2) when no `profile-read` tool call ran after the last user message, because the account's layer-2 `Preference` records (signature policy, header, naming, styling) were not consulted this turn, the exact miss that dropped a customer signature on a delivered document. **Block message:** `Blocked: this customer document is about to go out without the account's saved preferences being checked this turn. Those records hold the signature, header, naming and styling rules. Run profile-read for this account, apply anything relevant, then send again.` **Log line** (stderr): `[preference-gate] op=bypass tool=<name> detail=no profile-read this turn` on a block, `op=allow tool=<name> consulted=true` on an allowed document deliverable. Every non-document tool/shape, and every casual channel reply or plain-text email, passes at exit 0. **Fail-open** on an uninspectable call (tty / empty stdin / no `python3` / transcript missing or unreadable). Scope decision: the gate fires on document deliverables only, not on every send, so it never blocks routine chat. The standing reconcile counterpart for stranded `output/` deliverables is filed as a follow-up task.
-- `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/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). **Third check — a running header on every physical page.** Chrome decides physical pagination at print time, so a document whose header is a hand-placed `<div>` next to a hand-placed page break loses that header on any page the content bled onto (job 1854, 2026-08-04: 8 headerless pages out of 21, with `run-head` and `page-break` counts matching at 20 apiece, which is why counting the two against each other is blind to the fault). This check is deliberately **receipt-free and path-agnostic**, because template-seeded documents — budget estimates, valuations, works orders, survey sheets — never pass through `quote-render` and are exactly the ones that reproduce it. It resolves the source HTML from the render receipt when the PDF is a gated client quote, else from the sibling `<same-basename>.html` beside the PDF (the documented `browser-pdf-save` convention in `plugins/business-assistant/references/invoicing.md` step 4 and `plugins/business-assistant/references/document-management.md` step 4). The **header marker** is the literal string `content` of the first `@page` top margin box that carries one, tried `@top-center` → `@top-right` → `@top-left`, with CSS escapes and HTML entities resolved; a `content:url()` logo box carries no extractable text and is skipped, and a marker under 4 characters counts as absent. Pages are read one at a time with `pdftotext -f N -l N` **cropped to the top 12% of the page** and compared on whitespace-collapsed text. The crop is load-bearing, not an optimisation: a running footer routinely repeats the same reference as the header (the GLS footer is `… Builders Est. 1987 · Quote <ref>`), so a whole-page match reports a header on a page that carries only a footer — measured on a real 10-page print, where page 1 matched on its footer alone while its header was correctly suppressed. Twelve percent covers a top margin as deep as 30mm on A4 and excludes the footer. Checking starts at **page 2** when the source declares `@page :first` (which suppresses the boxes so page 1 keeps its own masthead) and from page 1 otherwise. It blocks (exit 2) when any checked page lacks the marker. **Only a document that declares a running header is ever gated** — a brochure or any document without one passes untouched. **Block message:** `Blocked: this printed document has physical pages carrying no running header, so it would go out with unbranded pages (…). 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.` **Log line:** `<ISO> [quote-render] op=pdf-header-conformance file=<basename> pages=<N> pagesChecked=<n> pagesHeaderless=<k> session=<sid>`, emitted on **every** decisive call including a clean one (`pagesHeaderless=0`), and on each skip path as `pagesChecked=0 reason=<no-source-html|no-running-header|single-page|no-poppler>` — so a clean run is distinguishable from a check that never ran. A block additionally emits `op=bypass file=<basename> reason=pdf-header-conformance detail=pagesHeaderless=<k> pages=<comma list>`. **Sink:** `<logDir>/quote-render-conformance.log`, resolved by the `LOG_DIR` → `CLAUDE_SESSION_MANAGER_PERSIST_DIR/logs` → `ACCOUNT_DIR/logs` ladder that `mailbox-inject.sh` uses, **not** `server.log` — a hook's stderr on exit 0 reaches no sink at all (measured 2026-08-06 on the laptop's `sitedesk-code` install: no bracketed hook line appears in `server.log` live or rotated, nor in the JSONL transcripts), so a stderr-only line would have been an audit nothing reads. The line is echoed to stderr as well, so a blocking run still shows it to the agent. **Fail-open** additionally on absent `pdfinfo`/`pdftotext`, an unresolvable source HTML, and a source that declares no running header. **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 answer 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-path-write-gate.test.sh

@@ -0,0 +1,152 @@
+#!/usr/bin/env bash
+# Regression test for quote-path-write-gate.sh.
+#
+# 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. 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, while leaving every other deliverable that agent owns untouched.
+#
+# The caller is identified by `agent_type` in the hook envelope, which Claude
+# Code sets when a hook fires inside a subagent. The MAXY_SPECIALIST env is not
+# usable: 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.
+#
+# Cards are resolved across 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.
+#
+# Covers:
+#   A. the quoter writing a quote document          → ALLOWED
+#   B. an agent without the tool                    → BLOCKED without-render-tool
+#   C. no agent_type at all (the main conversation) → BLOCKED without-render-tool
+#   D. an agent_type no card resolves               → BLOCKED unresolved-agent
+#   E. the internal pricing bucket                  → ALLOWED (never gated)
+#   F. an agent without the tool, quote templates   → BLOCKED
+#   G. the quoter, quote templates                  → ALLOWED
+#   H. an agent without the tool, its own output    → ALLOWED
+#   I. the Quotations bucket                        → BLOCKED
+#   J. empty stdin                                  → ALLOWED (fail-open)
+#   K. a read of a gated path                       → ALLOWED
+#   L. MultiEdit is gated like Write and Edit       → BLOCKED
+#   M. a block emits the op=bypass fault line
+
+set -u
+
+HOOK="$(cd "$(dirname "$0")/.." && pwd)/quote-path-write-gate.sh"
+if [[ ! -x "$HOOK" ]]; then
+  echo "FAIL: $HOOK not executable" >&2
+  exit 1
+fi
+
+FAKE=$(mktemp -d)
+cleanup() { rm -rf "$FAKE"; }
+trap cleanup EXIT
+
+ACCT="$FAKE/accounts/acct-1"
+mkdir -p "$ACCT/.claude/agents" "$ACCT/jobs/job-1/quote" "$ACCT/jobs/job-1/pricing" \
+         "$ACCT/quoting/templates" "$ACCT/output" \
+         "$FAKE/premium-plugins/sitedesk/agents" "$FAKE/platform/plugins/admin/hooks"
+
+# The per-account registry: a bundled specialist that holds no quote tool.
+cat > "$ACCT/.claude/agents/content-producer.md" <<'CARD'
+---
+name: content-producer
+description: "Produces documents."
+tools: Skill, Read, Write, Edit, MultiEdit, Bash, mcp__plugin_browser_browser__browser-pdf-save
+---
+CARD
+
+# The premium bundle: the quoter, whose card filename does not match its name.
+cat > "$FAKE/premium-plugins/sitedesk/agents/sitedesk--quoter.md" <<'CARD'
+---
+name: quoter
+description: "The quoter owns the client quote document entire."
+tools: Skill, Read, Write, Edit, Bash, mcp__plugin_sitedesk-job_sitedesk-job__quote-engine-run, mcp__plugin_sitedesk-job_sitedesk-job__quote-render
+---
+CARD
+
+PASS=0
+FAIL=0
+
+envelope() { # tool_name, file_path, agent_type ("" = absent)
+  python3 -c '
+import json, sys
+d = {"hook_event_name": "PreToolUse", "tool_name": sys.argv[1],
+     "tool_input": {"file_path": sys.argv[2]}}
+if sys.argv[3]:
+    d["agent_type"] = sys.argv[3]
+    d["agent_id"] = "agent_01"
+print(json.dumps(d))' "$1" "$2" "$3"
+}
+
+run_case() {
+  local name="$1" stdin="$2" expected_exit="$3"
+  local actual_exit
+  ( cd "$ACCT" && export PLATFORM_ROOT="$FAKE/platform" && 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
+}
+
+QUOTE="jobs/job-1/quote/Q 1879 - Client.html"
+
+run_case "A: the quoter writing a quote document → ALLOWED" \
+  "$(envelope Write "$QUOTE" sitedesk:quoter)" 0
+
+run_case "B: an agent without the tool → BLOCKED" \
+  "$(envelope Write "$QUOTE" content-producer)" 2
+
+run_case "C: no agent_type at all → BLOCKED" \
+  "$(envelope Write "$QUOTE" '')" 2
+
+run_case "D: an agent_type no card resolves → BLOCKED" \
+  "$(envelope Write "$QUOTE" ghost-agent)" 2
+
+run_case "E: the internal pricing bucket → ALLOWED" \
+  "$(envelope Write 'jobs/job-1/pricing/breakdown.md' content-producer)" 0
+
+run_case "F: an agent without the tool, quote templates → BLOCKED" \
+  "$(envelope Edit 'quoting/templates/house-style.html' content-producer)" 2
+
+run_case "G: the quoter, quote templates → ALLOWED" \
+  "$(envelope Edit 'quoting/templates/house-style.html' sitedesk:quoter)" 0
+
+run_case "H: an agent without the tool, its own output → ALLOWED" \
+  "$(envelope Write 'output/works-order.md' content-producer)" 0
+
+run_case "I: the Quotations bucket → BLOCKED" \
+  "$(envelope Write 'jobs/job-1/Quotations/Q 1879 - Client.html' content-producer)" 2
+
+run_case "J: empty stdin → ALLOWED (fail-open)" "" 0
+
+run_case "K: a read of a gated path → ALLOWED" \
+  "$(envelope Read "$QUOTE" content-producer)" 0
+
+run_case "L: MultiEdit is gated like Write and Edit → BLOCKED" \
+  "$(envelope MultiEdit "$QUOTE" content-producer)" 2
+
+check_reason() { # name, agent_type, expected reason
+  local out
+  out=$( cd "$ACCT" && export PLATFORM_ROOT="$FAKE/platform" && printf '%s' "$(envelope Write "$QUOTE" "$2")" | bash "$HOOK" 2>&1 >/dev/null )
+  if printf '%s' "$out" | grep -q "\[quote-render\] op=bypass reason=$3"; then
+    echo "PASS: M: $1 emits reason=$3"
+    PASS=$((PASS + 1))
+  else
+    echo "FAIL: M: $1 did not emit reason=$3 (got: $out)" >&2
+    FAIL=$((FAIL + 1))
+  fi
+}
+check_reason "an agent without the tool" content-producer quote-path-write-without-render-tool
+check_reason "an unresolvable agent"      ghost-agent     quote-path-write-unresolved-agent
+
+echo "──────── quote-path-write-gate test summary ────────"
+echo "PASS=$PASS FAIL=$FAIL"
+[[ "$FAIL" -eq 0 ]]

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

@@ -0,0 +1,95 @@
+#!/usr/bin/env bash
+# Regression test for quote-pdf-bash-gate.sh.
+#
+# quote-render-gate refuses a hand-authored client quote at browser-pdf-save.
+# An agent holding Bash reaches the same outcome with any HTML-to-PDF converter
+# and meets no control at all: the specialist that produced the 2026-08-05
+# quote holds Bash, Write, Edit and browser-pdf-save. This gate refuses a Bash
+# command that produces a PDF from an HTML under a gated quote path, matching
+# structurally on the paths so the rule holds for any converter binary.
+#
+# Covers:
+#   A. converting an HTML in a job's quote bucket        → BLOCKED
+#   B. converting an HTML in a job's Quotations bucket   → BLOCKED
+#   C. converting an HTML in the customer documents scope → BLOCKED
+#   D. a quoted path carrying spaces                     → BLOCKED
+#   E. the same converter on an unrelated HTML           → ALLOWED
+#   F. a read of a gated HTML, no PDF named              → ALLOWED
+#   G. the internal pricing bucket                       → ALLOWED (never gated)
+#   H. empty stdin                                       → ALLOWED (fail-open)
+#   I. a non-Bash tool                                   → ALLOWED
+#   J. a block emits the op=bypass fault line
+
+set -u
+
+HOOK="$(cd "$(dirname "$0")/.." && pwd)/quote-pdf-bash-gate.sh"
+if [[ ! -x "$HOOK" ]]; then
+  echo "FAIL: $HOOK not executable" >&2
+  exit 1
+fi
+
+PASS=0
+FAIL=0
+
+run_case() {
+  local name="$1" stdin="$2" expected_exit="$3"
+  local actual_exit
+  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() { # command
+  python3 -c '
+import json, sys
+print(json.dumps({
+    "hook_event_name": "PreToolUse",
+    "tool_name": "Bash",
+    "tool_input": {"command": sys.argv[1]},
+}))' "$1"
+}
+
+run_case "A: convert an HTML in a job quote bucket → BLOCKED" \
+  "$(envelope 'wkhtmltopdf jobs/job-1/quote/quote.html jobs/job-1/quote/quote.pdf')" 2
+
+run_case "B: convert an HTML in a job Quotations bucket → BLOCKED" \
+  "$(envelope 'chromium --headless --print-to-pdf=out.pdf jobs/job-1/Quotations/q.html')" 2
+
+run_case "C: convert an HTML in the customer documents scope → BLOCKED" \
+  "$(envelope 'weasyprint memory/users/44700900000/documents/quote-job-1.html q.pdf')" 2
+
+run_case "D: a quoted path carrying spaces → BLOCKED" \
+  "$(envelope 'wkhtmltopdf "jobs/job-1/quote/Q 1879 - Client.html" "jobs/job-1/quote/Q 1879 - Client.pdf"')" 2
+
+run_case "E: the same converter on an unrelated HTML → ALLOWED" \
+  "$(envelope 'wkhtmltopdf notes/readme.html readme.pdf')" 0
+
+run_case "F: a read of a gated HTML, no PDF named → ALLOWED" \
+  "$(envelope 'cat "jobs/job-1/quote/Q 1879 - Client.html"')" 0
+
+run_case "G: the internal pricing bucket → ALLOWED" \
+  "$(envelope 'wkhtmltopdf jobs/job-1/pricing/breakdown.html breakdown.pdf')" 0
+
+run_case "H: empty stdin → ALLOWED (fail-open)" "" 0
+
+run_case "I: a non-Bash tool → ALLOWED" \
+  '{"hook_event_name":"PreToolUse","tool_name":"Write","tool_input":{"file_path":"jobs/job-1/quote/q.html"}}' 0
+
+STDERR=$(printf '%s' "$(envelope 'wkhtmltopdf jobs/job-1/quote/quote.html jobs/job-1/quote/quote.pdf')" | bash "$HOOK" 2>&1 >/dev/null)
+if printf '%s' "$STDERR" | grep -q '\[quote-render\] op=bypass reason=bash-pdf-production'; then
+  echo "PASS: J: block emits op=bypass reason=bash-pdf-production"
+  PASS=$((PASS + 1))
+else
+  echo "FAIL: J: op=bypass line absent (got: $STDERR)" >&2
+  FAIL=$((FAIL + 1))
+fi
+
+echo "──────── quote-pdf-bash-gate test summary ────────"
+echo "PASS=$PASS FAIL=$FAIL"
+[[ "$FAIL" -eq 0 ]]