@rubytech/create-realagent-code 0.1.574 → 0.1.576

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

@@ -277,6 +277,9 @@ Tools are available via the `admin` MCP server.
 - `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/html-structure-gate.sh` — **PreToolUse matcher=`Write` / `Edit` / `MultiEdit`.** Refuses a write that would produce an HTML document with a `<style>` element opened inside another one, or with more openers than closers. The fault is not cosmetic: HTML parses style content as raw text, so the **first** `</style>` closes the outer element — everything after it becomes body content and renders as visible text, and the rule immediately after the stray opener is eaten as part of an invalid selector. One fault, two symptoms, both seen on a client quotation that went out on 2026-07-24 and was noticed on 2026-08-07. **Detector, three rules:** HTML comments are stripped first, each replaced by its own newlines, so a `<style>` inside `<!-- … -->` is not scanned and line numbers do not shift (two account templates carry one and are clean; a comment-blind detector reports both); `<style…>`/`</style…>` are then walked case-insensitively tracking depth, and an opener seen at depth > 0 is the fault; a CSS comment protects an **opener** but never a **closer**, because style content is raw text to the HTML parser so `</style>` terminates the element wherever it appears, while an opener is never a parse event inside a stylesheet — it is text the CSS parser reads as an invalid selector, and inside `/* … */` it is discarded (the shipped property-brochure `template.html` and `index.html` document their brand-token override slot exactly that way and are correct); at end of input openers must equal closers, and an unmatched opener is reported at its own line. The same three rules are implemented in the session manager's `html-structure-census`, which walks what is already on disk. **It walks the document the call would produce, not the fragment** — for `Write` that is `content`; for `Edit`/`MultiEdit` the on-disk file is read and the replacements applied in memory first, because the balance rule would otherwise refuse every partial edit and a nested opener whose outer `<style>` is already on disk would pass. **Scope is the whole account with an exclusion list, never a bucket list**: every `.html`/`.htm` resolving inside the account dir (this hook's cwd, as in `fs-schema-guard.sh`) except under `node_modules/`, `.wrangler/`, `.tool/`, `.trash/`. A bucket list is what let the live document through — it sat under `sites/<project>/public/`, which no quote bucket covers. `NotebookEdit` is deliberately not registered: a notebook is not a client document. **Block message:** `Blocked: this document opens a <style> element inside another one (line N). The browser closes the outer element at the first </style>, so the rest of the stylesheet renders as visible text on the page and the rule after the stray opener is discarded. Put the block in the body as its own <style> element, or merge its rules into the one already open.` **Log line:** `[html-structure-gate] op=refuse account=<id8> file=<json-quoted-path> line=<n>`, a direct append to `<logDir>/server.log` resolved by the `LOG_DIR` → `CLAUDE_SESSION_MANAGER_PERSIST_DIR/logs` → `<cwd>/logs` ladder, not a stderr echo. There is deliberately **no hard-coded brand fallback**: four brands are co-resident on the laptop, each with its own `~/.<brand>/logs`, so a literal would file this account's path in a sibling brand's `server.log`; when no rung resolves the line is dropped and the refusal still blocks. The path is JSON-quoted because these filenames carry spaces and a bare `key=value` line truncates at the first space. **Fail-open** on an uninspectable envelope (tty / empty stdin / unreadable target / unparseable edit).
+- `hooks/fs-schema-guard.sh` — **PreToolUse, registered on `Write` / `Edit` / `MultiEdit` / `NotebookEdit`; acts on `Write`, `Edit` and `NotebookEdit` only** — its tool dispatch has no `MultiEdit` arm, so a `MultiEdit` exits 0 unread and reaches every path this hook otherwise fences (verified by direct invocation, 2026-08-07; `archive-ingest-surface-gate.sh` has the same registered-but-unhandled gap and is tracked with it). The account-dir path guard. It enforces the seeded file schema (`<accountDir>/SCHEMA.md`) on this account's own layout — allowed top-level set, the account-machinery and declared-file deny fences, bucket depth, and the lowercase name convention — and, before any of that, refuses a target that resolves inside a **sibling account** under the same accounts root, for every session including a house-scoped one. Containment is decided on the resolved path, so a symlink planted under this account that points into a sibling is refused rather than read as an own-account path, and a sibling counts as an account only when it carries `account.json`. **Log line** (stderr, on a block): `[fs-guard] blocked path=<path> reason=<top-level|account-machinery|declared-file|over-deep|bad-name|cross-account>`, with `target=<acct8>` added on the cross-account reason. A cross-account block **also records the refused absolute path** in a per-session ledger under the tmpdir (`maxy-fsguard-refused-<sessionId>.txt`), which `fs-schema-guard-bash-post.sh` reads; recording is best-effort and never changes the verdict, and a call carrying no `session_id` records nothing. **Fail-closed** on an uninspectable call (tty / empty stdin); **fail-open** on a missing or empty schema, which governs this account's own layout only and never opens the cross-account path.
+- `hooks/fs-schema-guard-bash-pre.sh` — **PreToolUse matcher=`Bash`.** Records the account root's immediate top-level entry names before the command runs, into `maxy-fsguard-snapshot-<sessionId>.txt` under the tmpdir, so the PostToolUse twin can flag only the entries **this** command created rather than the legacy backlog. It inspects account-root state and never the command string. Always exits 0 — a snapshot that cannot be taken must not block a command, and blocking is the post hook's job.
+- `hooks/fs-schema-guard-bash-post.sh` — **PostToolUse matcher=`Bash`.** Two independent checks under one exit. **Strays:** diffing the account root against the pre-snapshot, an entry that appeared this command and is not in the allowed set is `[fs-guard-bash] stray path=<name> reason=top-level`, and a badly-named new child of a bucket created this command is `reason=bad-name`. **Evasion:** every path `fs-schema-guard.sh` refused as cross-account in this session that now **exists on disk** was written by some other route after the refusal, and is reported as `[fs-guard-bash] evaded path=<path> reason=cross-account target=<acct8>` — the pair to the guard's own `blocked` line on the same path and target, so a bypass is two grep-able lines rather than a transcript to read. A reported path is dropped from the ledger, so one evasion reports once. The path was refused in this session by this session's own hook, so existence afterwards is attribution: no sibling directory is walked and no mtime is read. The stray fail-opens (missing snapshot, empty allowed set) govern the stray check alone and do not gate the evasion check, because the path guard refuses a sibling target before it parses any schema — an account with no `SCHEMA.md`, and a session whose pre-hook failed open, can each still hold a recorded refusal. A missing or unreadable ledger reports nothing. **No filesystem mutation:** PostToolUse runs after the command, so it reports and never repairs; the standing account-dir reconcile is the net for anything the agent ignores.
 - `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). **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. **Fourth check — the running header image's geometry.** Chromium paints a page-margin box's `content:url()` at **intrinsic pixel size** (one image px to one CSS px at 96 px/in) and does **not** scale it to the box's declared `width`/`height`, so a full-resolution logo covers most of the page on every page the box paints — measured 2026-08-05 on a real print, a 700×252 asset in a declared 34mm box rendering 525.0 pt wide on a 594.96 pt A4 page, 88% of page width, against the corrected 125×45 derivative's 93.8 pt. It runs in the same offline stage as the header check, after it rather than instead of it, so **one print reports a headerless page and an oversized logo together** rather than surfacing the second only after the first is fixed and reprinted; both stages still precede the network fetch. **Only a document that declares an image in a `@page` top margin box is inspected** — a `@top-left|center|right` block whose `content` is a `url(...)` — so a brochure or a text-only running header is never gated. Using `pdfimages -list` it groups image rows by object id across the checked page range and asserts **only the running image, the object present on every checked page**, which is what a running header is by construction. The assertion is `width_px / x_ppi * 72 ≤ page_width / 3`, 198.3 pt on A4. Scoping to the running image is load-bearing, not an optimisation: measured across three real quotes, running headers occupy 9.0%, 15.8% and 18.9% of page width while **single-page content photos occupy 38.7% to 77.2%**, so a whole-page threshold at any value that catches the 88% defect blocks legitimate documents — a 33-page quote was measured carrying two 38.7% photos and a 21-page quote a 77.2% one. Nothing is asserted when the checked range is under two pages, since "present on every page" is vacuous there. **Block message:** `Blocked: the running header image on this printed document covers most of the page width (…). An image used as a page margin box's content is painted at its own pixel size and is not scaled down to the box you declared, so the image file itself has to be made the size the box expects. Shrink the asset, rebuild the document, print it again, and check a page after the first.` **Log line:** `op=pdf-image-geometry file=<basename> pagesChecked=<n> runningImages=<k> widestPt=<pt> fracPage=<pct>% limitPt=<pt>`, emitted whether or not it fails because it is the line that decides the verdict, and on a skip as `pagesChecked=0 reason=no-poppler`. A block additionally emits `op=bypass file=<basename> reason=pdf-header-image-geometry detail=widestPt=… fracPage=…% limitPt=…`. **Every skip now names its reason.** The link stage returned silently at seven points; each emits `op=skip reason=<bad-envelope|not-browser-tool|no-path|not-gated|bad-jobid|no-receipt|no-source>`, because a silent return is indistinguishable from a gate that never ran — which is the state a stale PostToolUse matcher actually leaves an account in. Fail-open behaviour itself is unchanged; only its visibility. The two returns taken before the log sink resolves (tty stdin, empty stdin) stay silent: there is no log directory or session id at that point. **Standing audit.** The gate only fires on a print, so four failure modes emit nothing and do not reproduce on demand: the gate passing a defective PDF, the gate never matching the path, a template drifting back to a full-resolution asset, and a stale document never re-rendered. `claude-session-manager`'s `quote-print-census.ts` sweeps hourly, emitting `[quote-print-census] scanned=<N> pdfs=<N> sourceHtml=<N> headerMissingPages=<N> oversizedImages=<N> unreadable=<N>` to `server.log`. It does **not** re-implement either rule: it invokes this hook once per PDF with `LOG_DIR`/`CLAUDE_SESSION_MANAGER_PERSIST_DIR`/`ACCOUNT_DIR` stripped, so the hook resolves no log directory, writes no file, and returns its verdict on stderr — one implementation, no drift. Its source-HTML half reads each margin-box image's intrinsic PNG width directly (over 264 px cannot fit a third of an A4 page at 96 px/in), which sees a drifted template **before** anything is printed from it. Healthy is `headerMissingPages=0 oversizedImages=0` with `pdfs` non-zero; the leak signature is `oversizedImages` above zero with no `op=bypass` ever emitted, meaning defective documents exist the gate never saw. A PDF that produced no verdict line, or a `no-poppler` skip, counts `unreadable` rather than clean. **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.

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

@@ -168,6 +168,112 @@ printf '{}' > "$L/wa-channel-bindings.json"
 run_post "$L" "$(env_json PostToolUse Bash "$SID")" "$ef"
 check "post silent on declared file" 0 $? "" "$(cat "$ef")"
 
+# --- Evasion reporting (the refusal ledger's read side) ----------------------
+# A two-account root so a recorded absolute path yields the same target=<acct8>
+# the Write/Edit guard's blocked line carries. new_acct() builds a standalone dir
+# with no account parent, which cannot exercise that derivation.
+new_root() {
+  local r; r=$(mktemp -d)
+  mkdir -p "$r/20028fb5-own/projects" "$r/75127c89-sibling/projects"
+  cp "$TEMPLATE" "$r/20028fb5-own/SCHEMA.md"
+  printf '{"accountId":"20028fb5-own"}'     > "$r/20028fb5-own/account.json"
+  printf '{"accountId":"75127c89-sibling"}' > "$r/75127c89-sibling/account.json"
+  printf '%s' "$r"
+}
+LEDGER="$SNAP_TMP/maxy-fsguard-refused-${SID}.txt"
+realpath_of() { python3 -c 'import os,sys; print(os.path.realpath(sys.argv[1]))' "$1"; }
+# Seed the ledger exactly as fs-schema-guard.sh writes it: one resolved absolute
+# path per line.
+seed_ledger() { realpath_of "$1" > "$LEDGER"; }
+
+# --- 16. An evasion and a stray in one command: both under one exit 2 --------
+R1=$(new_root); OWN1="$R1/20028fb5-own"; EV1="$R1/75127c89-sibling/projects/spine.md"
+run_pre "$OWN1" "$(env_json PreToolUse Bash "$SID")" "$ef"
+seed_ledger "$EV1"
+: > "$EV1"                 # the cp that walks around the refusal
+mkdir "$OWN1/whim"         # an unrelated stray in the same command
+run_post "$OWN1" "$(env_json PostToolUse Bash "$SID")" "$ef"; rc=$?
+err="$(cat "$ef")"
+if [ $rc -eq 2 ] \
+   && printf '%s' "$err" | grep -qF "[fs-guard-bash] evaded path=$(realpath_of "$EV1") reason=cross-account target=75127c89" \
+   && printf '%s' "$err" | grep -qF "[fs-guard-bash] stray path=whim reason=top-level"; then
+  echo "PASS: post reports evasion alongside stray"; PASS=$((PASS+1));
+else echo "FAIL: evasion+stray (exit=$rc): $err" >&2; FAIL=$((FAIL+1)); fi
+
+# --- 17. The same path is not reported again on the next Bash call ------------
+run_post "$OWN1" "$(env_json PostToolUse Bash "$SID")" "$ef"; rc=$?
+err="$(cat "$ef")"
+if ! printf '%s' "$err" | grep -q "evaded"; then
+  echo "PASS: evasion reports once (exit=$rc)"; PASS=$((PASS+1));
+else echo "FAIL: evasion re-reported (exit=$rc): $err" >&2; FAIL=$((FAIL+1)); fi
+
+# --- 18. An evasion with no stray still exits 2 ------------------------------
+# The ledger alone is a finding: the write already happened in another account.
+R2=$(new_root); OWN2="$R2/20028fb5-own"; EV2="$R2/75127c89-sibling/projects/plan.md"
+run_pre "$OWN2" "$(env_json PreToolUse Bash "$SID")" "$ef"
+seed_ledger "$EV2"
+: > "$EV2"
+run_post "$OWN2" "$(env_json PostToolUse Bash "$SID")" "$ef"
+check "post blocks on evasion alone" 2 $? "\[fs-guard-bash\] evaded path=.*reason=cross-account target=75127c89" "$(cat "$ef")"
+
+# --- 19. A recorded path that never appeared -> silent ----------------------
+# The agent complied with the refusal, so there is nothing to report.
+R3=$(new_root); OWN3="$R3/20028fb5-own"; EV3="$R3/75127c89-sibling/projects/absent.md"
+run_pre "$OWN3" "$(env_json PreToolUse Bash "$SID")" "$ef"
+seed_ledger "$EV3"
+run_post "$OWN3" "$(env_json PostToolUse Bash "$SID")" "$ef"
+check "post silent when refusal held" 0 $? "" "$(cat "$ef")"
+rm -f "$LEDGER"
+
+# --- 20. No ledger at all -> today's behaviour, unchanged --------------------
+R4=$(new_root); OWN4="$R4/20028fb5-own"
+run_pre "$OWN4" "$(env_json PreToolUse Bash "$SID")" "$ef"
+run_post "$OWN4" "$(env_json PostToolUse Bash "$SID")" "$ef"
+check "post fail-open no-ledger" 0 $? "" "$(cat "$ef")"
+
+# --- 21. An unreadable ledger fails open exactly like a missing one ----------
+R5=$(new_root); OWN5="$R5/20028fb5-own"; EV5="$R5/75127c89-sibling/projects/x.md"
+run_pre "$OWN5" "$(env_json PreToolUse Bash "$SID")" "$ef"
+seed_ledger "$EV5"; : > "$EV5"; chmod 000 "$LEDGER"
+run_post "$OWN5" "$(env_json PostToolUse Bash "$SID")" "$ef"; rc=$?
+chmod 644 "$LEDGER"; rm -f "$LEDGER"
+check "post fail-open unreadable ledger" 0 "$rc" "" "$(cat "$ef")"
+
+# --- 22. No SCHEMA.md: the empty-allowed-set fail-open governs strays only ----
+# The path guard refuses a sibling target BEFORE it parses any schema, so an
+# account with no SCHEMA.md can still hold a recorded refusal. Swallowing the
+# evasion report here would lose the signal for exactly that account shape.
+R6=$(new_root); OWN6="$R6/20028fb5-own"; EV6="$R6/75127c89-sibling/projects/noschema.md"
+rm -f "$OWN6/SCHEMA.md"
+run_pre "$OWN6" "$(env_json PreToolUse Bash "$SID")" "$ef"
+seed_ledger "$EV6"
+: > "$EV6"
+run_post "$OWN6" "$(env_json PostToolUse Bash "$SID")" "$ef"
+check "post reports evasion without own schema" 2 $? "\[fs-guard-bash\] evaded path=.*target=75127c89" "$(cat "$ef")"
+rm -f "$LEDGER"
+
+# --- 23. A missing pre-snapshot governs the stray check only -----------------
+# This case needs its OWN session id: $SID's snapshot file is written by every
+# earlier run_pre in this suite and is still on disk, so reusing $SID would not
+# model a missing snapshot.
+NOSNAP_SID="nosnap-session-2506"
+NOSNAP_LEDGER="$SNAP_TMP/maxy-fsguard-refused-${NOSNAP_SID}.txt"
+R7=$(new_root); OWN7="$R7/20028fb5-own"; EV7="$R7/75127c89-sibling/projects/nosnap.md"
+: > "$EV7"
+realpath_of "$EV7" > "$NOSNAP_LEDGER"
+run_post "$OWN7" "$(env_json PostToolUse Bash "$NOSNAP_SID")" "$ef"
+check "post reports evasion without pre-snapshot" 2 $? "\[fs-guard-bash\] evaded path=.*target=75127c89" "$(cat "$ef")"
+rm -f "$NOSNAP_LEDGER"
+
+# --- 24. The ledger is per-session ------------------------------------------
+R8=$(new_root); OWN8="$R8/20028fb5-own"; EV8="$R8/75127c89-sibling/projects/other.md"
+: > "$EV8"
+seed_ledger "$EV8"
+run_post "$OWN8" "$(env_json PostToolUse Bash "another-session-2506")" "$ef"
+check "post ignores another session's ledger" 0 $? "" "$(cat "$ef")"
+rm -f "$LEDGER"
+rm -rf "$R1" "$R2" "$R3" "$R4" "$R5" "$R6" "$R7" "$R8"
+
 rm -f "$ef"
 echo "----- $PASS passed, $FAIL failed -----"
 [ $FAIL -eq 0 ]

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

@@ -253,5 +253,71 @@ run_case "symlink into a sibling blocked" \
   "$(mkenv Edit file_path "$ACCT_OWN/documents/escape/index.html")" \
   2 'reason=cross-account target=5e99bba5' "$ACCT_OWN"
 
+# Refusal ledger: a refused cross-account path is recorded so the Bash post-hook
+# can report it if a later shell command lands it anyway. Isolated tmp so the run
+# never collides with a live session's ledger.
+LEDGER_TMP=$(mktemp -d)
+trap 'rm -rf "$ACCT" "$ACCT_D" "$ACCT_F" "$ACCT_L" "$ACCT_M" "$ROOT" "$LEDGER_TMP"' EXIT
+LSID="test-session-2506"
+LEDGER="$LEDGER_TMP/maxy-fsguard-refused-${LSID}.txt"
+
+# Same contract as run_case, with a session_id in the envelope and the ledger
+# tmpdir overridden for the single call.
+mkenv_sid() { printf '{"hook_event_name":"PreToolUse","tool_name":"%s","session_id":"%s","tool_input":{"%s":"%s"}}' "$1" "$2" "$3" "$4"; }
+run_case_ledger() { # name stdin expected_exit expected_log_re acct
+  local name="$1" stdin="$2" exp="$3" re="$4" acct="$5" ef actual
+  ef=$(mktemp)
+  ( cd "$acct" && printf '%s' "$stdin" | FS_GUARD_BASH_TMPDIR="$LEDGER_TMP" bash "$HOOK" >/dev/null 2>"$ef" )
+  actual=$?
+  local sc; sc=$(cat "$ef"); rm -f "$ef"
+  local ok=1
+  [ "$actual" -eq "$exp" ] || ok=0
+  if [ -n "$re" ] && ! printf '%s' "$sc" | grep -Eq "$re"; then ok=0; fi
+  if [ $ok -eq 1 ]; then echo "PASS: $name (exit=$actual)"; PASS=$((PASS+1));
+  else echo "FAIL: $name (exit=$actual, want $exp; log want /$re/)" >&2; FAIL=$((FAIL+1)); fi
+}
+# No ledger file of any name in the isolated tmpdir.
+assert_no_ledger() { # name
+  local n; n=$(ls "$LEDGER_TMP"/maxy-fsguard-refused-* 2>/dev/null | wc -l | tr -d ' ')
+  if [ "$n" = "0" ]; then echo "PASS: $1"; PASS=$((PASS+1));
+  else echo "FAIL: $1 (found $n ledger file(s))" >&2; FAIL=$((FAIL+1)); fi
+}
+# The hook records os.path.realpath of the target; resolve the same way here so
+# the comparison does not fail on a symlinked mktemp root.
+realpath_of() { python3 -c 'import os,sys; print(os.path.realpath(sys.argv[1]))' "$1"; }
+
+# A cross-account refusal records the resolved absolute path.
+rm -f "$LEDGER_TMP"/maxy-fsguard-refused-*
+XTARGET="$ACCT_SIB/sites/public/index.html"
+run_case_ledger "ledger refusal still blocks" \
+  "$(mkenv_sid Edit "$LSID" file_path "$XTARGET")" \
+  2 'reason=cross-account target=5e99bba5' "$ACCT_OWN"
+if [ -f "$LEDGER" ] && grep -qxF "$(realpath_of "$XTARGET")" "$LEDGER"; then
+  echo "PASS: ledger holds resolved absolute path"; PASS=$((PASS+1));
+else echo "FAIL: ledger missing or wrong content at $LEDGER" >&2; FAIL=$((FAIL+1)); fi
+
+# No session id: the refusal is unchanged and nothing is recorded, because the
+# ledger is keyed on the session and an unkeyed one could not be read back.
+rm -f "$LEDGER_TMP"/maxy-fsguard-refused-*
+run_case_ledger "ledger no session id still blocks" \
+  "$(mkenv Edit file_path "$ACCT_SIB/sites/public/index.html")" \
+  2 'reason=cross-account' "$ACCT_OWN"
+assert_no_ledger "ledger no session id writes nothing"
+
+# An own-account write is not a refusal, so it records nothing.
+rm -f "$LEDGER_TMP"/maxy-fsguard-refused-*
+run_case_ledger "ledger own-account allowed" \
+  "$(mkenv_sid Write "$LSID" file_path "$ACCT_OWN/documents/a.pdf")" \
+  0 "" "$ACCT_OWN"
+assert_no_ledger "ledger own-account writes nothing"
+
+# A path outside the accounts root is allowed here, so it records nothing.
+rm -f "$LEDGER_TMP"/maxy-fsguard-refused-*
+run_case_ledger "ledger out-of-tree allowed" \
+  "$(mkenv_sid Write "$LSID" file_path '/etc/passwd')" \
+  0 "" "$ACCT_OWN"
+assert_no_ledger "ledger out-of-tree writes nothing"
+rm -f "$LEDGER_TMP"/maxy-fsguard-refused-*
+
 echo "----- $PASS passed, $FAIL failed -----"
 [ $FAIL -eq 0 ]

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

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

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

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

package/payload/platform/plugins/admin/mcp/dist/index.js

@@ -993,7 +993,7 @@ lifelineTool(server, "plugin-toggle-enabled", "Enable or disable a plugin in thi
 eagerTool(server, "admin-add", "Add a new admin user to this account. Creates a device-level user entry (users.json) and adds them to this account's admins list (account.json). PIN must be at least 4 digits. If no PIN is provided, a unique 4-digit PIN is generated. Returns the userId and PIN to share with the new admin.\n\nIMPORTANT — retry behaviour: if the user already stated a specific PIN earlier in the conversation and a first admin-add call failed (e.g. tier cap reached, PIN collision), every retry MUST re-pass that PIN as the `pin` parameter. Omitting `pin` on the retry auto-generates a different 4-digit PIN, silently substituting what the user asked for.", {
     name: z.string().describe("Display name for the new admin (stored on the AdminUser node in Neo4j)."),
     pin: z.string().optional().describe("Optional PIN (minimum 4 digits). If omitted, a unique 4-digit PIN is generated."),
-    phone: z.string().optional().describe("E.164 phone (e.g. +441234567890) binding this admin to their WhatsApp sender. Without it a WhatsApp turn from this person resolves to no admin and their answer reaches only the door it arrived on. Settable later with admin-bind."),
+    phone: z.string().optional().describe("E.164 phone (e.g. +441234567890) binding this admin to their WhatsApp sender. Without it a WhatsApp turn from this person resolves to no admin. Settable later with admin-bind."),
     telegram: z.string().optional().describe("Telegram chat id binding this admin to their Telegram chat (negative for a group). Without it a Telegram turn from this person resolves to no admin. Settable later with admin-bind."),
 }, async ({ name, pin: rawPin, phone, telegram }) => {
     if (!ACCOUNT_ID)
@@ -1437,7 +1437,7 @@ eagerTool(server, "admin-update-pin", "Update an existing admin user's PIN. Defa
         content: [{ type: "text", text: `PIN updated${self ? "" : ` for userId ${userId}`}. The new PIN takes effect on the next login.` }],
     };
 });
-lifelineTool(server, "admin-bind", "Bind an admin to their channels by setting the phone and/or Telegram chat id on their users.json entry. This is what lets one answer reach every channel that person holds: without it a WhatsApp or Telegram turn resolves to no admin and the answer reaches only the door it arrived on. Defaults to the calling admin; pass userId (from admin-list) to bind someone else, which additionally requires confirm=true because a binding decides whose identity an inbound resolves to. Sets only the fields supplied; an omitted field is left untouched. A new admin can be born bound by passing the same fields to admin-add.", {
+lifelineTool(server, "admin-bind", "Bind an admin to their channels by setting the phone and/or Telegram chat id on their users.json entry. This is what makes an inbound turn resolve AS that person: without it a WhatsApp or Telegram turn from them resolves to no admin. It does not affect where an answer goes, which is always the door the message arrived on. Defaults to the calling admin; pass userId (from admin-list) to bind someone else, which additionally requires confirm=true because a binding decides whose identity an inbound resolves to. Sets only the fields supplied; an omitted field is left untouched. A new admin can be born bound by passing the same fields to admin-add.", {
     userId: z.string().optional().describe("The userId of the admin to bind. Defaults to the caller (the admin invoking this tool)."),
     phone: z.string().optional().describe("E.164 phone (e.g. +441234567890) binding this admin to their WhatsApp sender."),
     telegram: z.string().optional().describe("Telegram chat id binding this admin to their Telegram chat (negative for a group)."),