@rubytech/create-realagent-code 0.1.572 → 0.1.574

package/payload/platform/lib/routine-templates/src/index.ts

@@ -32,8 +32,20 @@
  */
 import { ROUTINE_ROSTER, ROUTINE_TEMPLATE_VERSION, type RoutineTemplate } from "./roster.js";
 
-export { ROUTINE_ROSTER, ROUTINE_ROSTER_KEYS, ROUTINE_TEMPLATE_VERSION } from "./roster.js";
-export type { RoutineTemplate } from "./roster.js";
+// Task 2471 — `isWatermarkedCheck` and `gateNeedsCommit` were declared but not
+// re-exported, so the only callers they ever had were this lib's own tests and
+// the invariant they express went unenforced at both gate write paths. They are
+// public now so the scheduling plugin's `validateGate` can reuse them, rather
+// than restating which check types carry a watermark and letting the two lists
+// drift.
+export {
+  ROUTINE_ROSTER,
+  ROUTINE_ROSTER_KEYS,
+  ROUTINE_TEMPLATE_VERSION,
+  isWatermarkedCheck,
+  gateNeedsCommit,
+} from "./roster.js";
+export type { RoutineTemplate, RoutineGate, RoutineGateCheck } from "./roster.js";
 
 /** The minimal Neo4j session surface the seed needs. Both the admin plugin's
  *  `getSession()` and a driver session from `seed-cli` satisfy it; the tests

package/payload/platform/plugins/admin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "admin",
-  "description": "Platform administration plugin. Provides system-status, public-hostname (deterministic Cloudflare public-URL resolver, single call returning the operator's canonical hostname so agents never guess property names on :CloudflareHostname nodes), admin-hostname (the admin-host twin of public-hostname — resolves the host that serves /calendar and the rest of the admin shell behind sign-in from the same ingress + alias + operator files, so agents point the operator at the admin /calendar URL instead of the public host that 404s it), publish-site (move an extracted static-site tree under <accountDir>/sites/<slug>/, emit one canonical path slug, and refresh llms.txt at the site root — typed refusal taxonomy replaces the prior skill-prose contract), brand-settings, account-manage, capabilities-here (deterministic install-introspection — returns enabledPlugins, tier, models, installed platform + premium specialists, registered Claude Code agent types, and the brand block as a single JSON object; the canonical tool for grounding any claim about what is enabled on the current account), linkedin-ingest-token (returns the account's durable LinkedIn ingest token — the one credential the Real Agent LinkedIn Ingest Chrome extension needs in its options page; minted on first call then stable across restarts and new chat sessions, and never a conversation session key nor the admin browser's session_key, which the ingest route rejects; action='rotate' replaces it and invalidates every existing extension install), account-update, the multi-account managed-service lifecycle tools (account_list, account_create, account_delete, account_purge, account_channel_routing, account_channel_routing_set — one Rubytech operator hosting N client accounts on one house install; create/delete/purge are operator-only and purge is two-step with a typed confirmation; account_create requires the client business owner's real name (ownerName), refusing a blank or the placeholder \"Owner\" and seeding it onto the sub-account's owner AdminUser and owner Person, and requires the owner's IANA timezone (timezone) — refusing a blank or a non-IANA value — seeding it onto the owner UserProfile marked owner-set so scheduling reads the owner's real zone from the start rather than the box's server default, while a managing house admin (its userId) is optional — when supplied it is validated as a live house admin and recorded as the sub-account's managingAdminUserId, and when omitted the sub-account is unmanaged and its passive-intake tasks route to the install's primary admin; account_reassign_admin repoints a client sub-account's managing admin to another live house admin (the repair path for a dangling managingAdminUserId, or to record one on an unmanaged account); account_roster is the canonical per-account identity view — one row per sub-account giving business name, role, the managing house admin resolved to a name with status (assigned/absent/dangling), the business owner from the graph with status (named/nameless), and the WhatsApp account-manager binding if any, each field carrying what it means and does not (managing admin is the responsible house team member not the owner; account manager is WhatsApp routing only with no admin rights), so the agent never stitches admin-list + account.json + whatsapp-config; account_set_owner_name names (or corrects) a client sub-account's business owner by writing the owned Person — the canonical name source — refusing a blank or the placeholder \"Owner\", the guarded repair for a nameless owner (the standing identity-audit op=nameless-owned-person detector); account_channel_routing_set repoints the house-paired WhatsApp/Telegram inbound stream to a different sub-account, and does not affect a sub-account's own separately paired WhatsApp number), admin-add (refuses on a client sub-account, where admin access is already install-wide so a per-operator seat grants nothing — the sub-account's one identity, its business owner, is set at account creation; the house account, where operators hold PIN logins and admins[] rows, is unchanged), admin-remove (refuses to remove a house admin who still manages one or more client sub-accounts, naming them so the operator reassigns each with account_reassign_admin first — never silently orphans them), admin-list, admin-update-pin, agent-list, agent-config-read, the public-agent write tools (agent-create is the only supported way to create a public agent: it validates the slug against the same rule the router serves by, validates config.json against the servable schema, refuses an empty KNOWLEDGE, writes the four files with IDENTITY.md copied verbatim from the platform template, and projects the agent into the graph in the same call, reporting the verified projected count rather than assuming it; agent-update applies the same validation to a merged config, writes only the fields supplied, and re-projects, so the graph cannot fall behind the files; agent-delete removes the :Agent node and its owned knowledge projections before the directory and refuses the admin agent — writing these files by hand reaches none of those checks, which is what left an agent on disk and absent from the graph for a day), agent-image, plugin-toggle-enabled, premium-list, premium-deliver, skill-find, logs-read, cpu-triage-start and cpu-triage-read (the two-call device CPU diagnostic — start spawns a detached sampling run across at least one full 120s reconcile cycle and returns a run handle immediately, read returns running/complete/failed with the per-core distribution; no admin tool blocks through a sampling window, and no spot reading is obtainable), plugin-read, skill-load (one-call resolve+read for SKILL.md by skill name, the canonical primitive for loading a named skill; plugin-read remains the reader for references/* and PLUGIN.md), skill-search (free-text intent → skill resolver: ranks every plugin skill's SKILL.md name+description against a query and returns the top owners with their canonical skills/<slug>/ path, so intent→skill mapping survives the available-skills menu leaving context after a compaction), store-skill (deterministic write counterpart to plugin-read; persists operator-authored skills as plugin files under the active account), session-reset, session-resume, wifi, and action-approval tools (action-pending, action-approve, action-reject, action-edit) for managing the Real Agent platform.",
+  "description": "Platform administration plugin. Provides system-status, public-hostname (deterministic Cloudflare public-URL resolver, single call returning the operator's canonical hostname so agents never guess property names on :CloudflareHostname nodes), admin-hostname (the admin-host twin of public-hostname — resolves the host that serves /calendar and the rest of the admin shell behind sign-in from the same ingress + alias + operator files, so agents point the operator at the admin /calendar URL instead of the public host that 404s it), publish-site (move an extracted static-site tree under <accountDir>/sites/<slug>/, emit one canonical path slug, and refresh llms.txt at the site root — typed refusal taxonomy replaces the prior skill-prose contract), brand-settings, account-manage, capabilities-here (deterministic install-introspection — returns enabledPlugins, tier, models, installed platform + premium specialists, registered Claude Code agent types, and the brand block as a single JSON object; the canonical tool for grounding any claim about what is enabled on the current account), linkedin-ingest-token (returns the account's durable LinkedIn ingest token — the one credential the Real Agent LinkedIn Ingest Chrome extension needs in its options page; minted on first call then stable across restarts and new chat sessions, and never a conversation session key nor the admin browser's session_key, which the ingest route rejects; action='rotate' replaces it and invalidates every existing extension install), account-update, the multi-account managed-service lifecycle tools (account_list, account_create, account_delete, account_purge, account_channel_routing, account_channel_routing_set — one Rubytech operator hosting N client accounts on one house install; create/delete/purge are operator-only and purge is two-step with a typed confirmation; account_create requires the client business owner's real name (ownerName), refusing a blank or the placeholder \"Owner\" and seeding it onto the sub-account's owner AdminUser and owner Person, and requires the owner's IANA timezone (timezone) — refusing a blank or a non-IANA value — seeding it onto the owner UserProfile marked owner-set so scheduling reads the owner's real zone from the start rather than the box's server default, while a managing house admin (its userId) is optional — when supplied it is validated as a live house admin and recorded as the sub-account's managingAdminUserId, and when omitted the sub-account is unmanaged and its passive-intake tasks route to the install's primary admin; account_reassign_admin repoints a client sub-account's managing admin to another live house admin (the repair path for a dangling managingAdminUserId, or to record one on an unmanaged account); account_roster is the canonical per-account identity view — one row per sub-account giving business name, role, the managing house admin resolved to a name with status (assigned/absent/dangling), the business owner from the graph with status (named/nameless), and the WhatsApp account-manager binding if any, each field carrying what it means and does not (managing admin is the responsible house team member not the owner; account manager is WhatsApp routing only with no admin rights), so the agent never stitches admin-list + account.json + whatsapp-config; account_set_owner_name names (or corrects) a client sub-account's business owner by writing the owned Person — the canonical name source — refusing a blank or the placeholder \"Owner\", the guarded repair for a nameless owner (the standing identity-audit op=nameless-owned-person detector); account_channel_routing_set repoints the house-paired WhatsApp/Telegram inbound stream to a different sub-account, and does not affect a sub-account's own separately paired WhatsApp number), admin-add (refuses on a client sub-account, where admin access is already install-wide so a per-operator seat grants nothing — the sub-account's one identity, its business owner, is set at account creation; the house account, where operators hold PIN logins and admins[] rows, is unchanged), admin-remove (refuses to remove a house admin who still manages one or more client sub-accounts, naming them so the operator reassigns each with account_reassign_admin first — never silently orphans them), admin-list, admin-update-pin, admin-bind (sets the phone and/or Telegram chat id on an admin's users.json entry — the binding resolveAdminUserId reads; without it a channel turn from that person resolves to no admin and the answer reaches only the door it arrived on, while a new admin is born bound by passing the same fields to admin-add. Defaults to the calling admin and routes an explicit userId through the same cross-identity gate the PIN tools use, requiring confirm=true, because a binding decides whose identity an inbound resolves to), agent-list, agent-config-read, the public-agent write tools (agent-create is the only supported way to create a public agent: it validates the slug against the same rule the router serves by, validates config.json against the servable schema, refuses an empty KNOWLEDGE, writes the four files with IDENTITY.md copied verbatim from the platform template, and projects the agent into the graph in the same call, reporting the verified projected count rather than assuming it; agent-update applies the same validation to a merged config, writes only the fields supplied, and re-projects, so the graph cannot fall behind the files; agent-delete removes the :Agent node and its owned knowledge projections before the directory and refuses the admin agent — writing these files by hand reaches none of those checks, which is what left an agent on disk and absent from the graph for a day), agent-image, plugin-toggle-enabled, premium-list, premium-deliver, skill-find, logs-read, cpu-triage-start and cpu-triage-read (the two-call device CPU diagnostic — start spawns a detached sampling run across at least one full 120s reconcile cycle and returns a run handle immediately, read returns running/complete/failed with the per-core distribution; no admin tool blocks through a sampling window, and no spot reading is obtainable), plugin-read, skill-load (one-call resolve+read for SKILL.md by skill name, the canonical primitive for loading a named skill; plugin-read remains the reader for references/* and PLUGIN.md), skill-search (free-text intent → skill resolver: ranks every plugin skill's SKILL.md name+description against a query and returns the top owners with their canonical skills/<slug>/ path, so intent→skill mapping survives the available-skills menu leaving context after a compaction), store-skill (deterministic write counterpart to plugin-read; persists operator-authored skills as plugin files under the active account), session-reset, session-resume, wifi, and action-approval tools (action-pending, action-approve, action-reject, action-edit) for managing the Real Agent platform.",
   "version": "0.1.0",
   "author": {
     "name": "Rubytech LLC"

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

@@ -1,7 +1,7 @@
 ---
 name: admin
 surface: platform
-description: "Platform administration plugin. Provides system-status, public-hostname (deterministic Cloudflare public-URL resolver, single call returning the operator's canonical hostname so agents never guess property names on :CloudflareHostname nodes), admin-hostname (the admin-host twin of public-hostname — resolves the host that serves /calendar and the rest of the admin shell behind sign-in from the same ingress + alias + operator files, so agents point the operator at the admin /calendar URL instead of the public host that 404s it), publish-site (move an extracted static-site tree under <accountDir>/sites/<slug>/, emit one canonical path slug, and refresh llms.txt at the site root — typed refusal taxonomy replaces the prior skill-prose contract), brand-settings, account-manage, capabilities-here (deterministic install-introspection — returns enabledPlugins, tier, models, installed platform + premium specialists, registered Claude Code agent types, and the brand block as a single JSON object; the canonical tool for grounding any claim about what is enabled on the current account), linkedin-ingest-token (returns the account's durable LinkedIn ingest token — the one credential the Real Agent LinkedIn Ingest Chrome extension needs in its options page; minted on first call then stable across restarts and new chat sessions, and never a conversation session key nor the admin browser's session_key, which the ingest route rejects; action='rotate' replaces it and invalidates every existing extension install), account-update, the multi-account managed-service lifecycle tools (account_list, account_create, account_delete, account_purge, account_channel_routing, account_channel_routing_set — one Rubytech operator hosting N client accounts on one house install; create/delete/purge are operator-only and purge is two-step with a typed confirmation; account_create requires the client business owner's real name (ownerName), refusing a blank or the placeholder "Owner" and seeding it onto the sub-account's owner AdminUser and owner Person, and requires the owner's IANA timezone (timezone) — refusing a blank or a non-IANA value — seeding it onto the owner UserProfile marked owner-set so scheduling reads the owner's real zone from the start rather than the box's server default, while a managing house admin (its userId) is optional — when supplied it is validated as a live house admin and recorded as the sub-account's managingAdminUserId, and when omitted the sub-account is unmanaged and its passive-intake tasks route to the install's primary admin; account_reassign_admin repoints a client sub-account's managing admin to another live house admin (the repair path for a dangling managingAdminUserId, or to record one on an unmanaged account); account_roster is the canonical per-account identity view — one row per sub-account giving business name, role, the managing house admin resolved to a name with status (assigned/absent/dangling), the business owner from the graph with status (named/nameless), and the WhatsApp account-manager binding if any, each field carrying what it means and does not (managing admin is the responsible house team member not the owner; account manager is WhatsApp routing only with no admin rights), so the agent never stitches admin-list + account.json + whatsapp-config; account_set_owner_name names (or corrects) a client sub-account's business owner by writing the owned Person — the canonical name source — refusing a blank or the placeholder "Owner", the guarded repair for a nameless owner (the standing identity-audit op=nameless-owned-person detector); account_channel_routing_set repoints the house-paired WhatsApp/Telegram inbound stream to a different sub-account, and does not affect a sub-account's own separately paired WhatsApp number), admin-add (refuses on a client sub-account, where admin access is already install-wide so a per-operator seat grants nothing — the sub-account's one identity, its business owner, is set at account creation; the house account, where operators hold PIN logins and admins[] rows, is unchanged), admin-remove (refuses to remove a house admin who still manages one or more client sub-accounts, naming them so the operator reassigns each with account_reassign_admin first — never silently orphans them), admin-list, admin-update-pin, agent-list, agent-config-read, the public-agent write tools (agent-create is the only supported way to create a public agent: it validates the slug against the same rule the router serves by, validates config.json against the servable schema, refuses an empty KNOWLEDGE, writes the four files with IDENTITY.md copied verbatim from the platform template, and projects the agent into the graph in the same call, reporting the verified projected count rather than assuming it; agent-update applies the same validation to a merged config, writes only the fields supplied, and re-projects, so the graph cannot fall behind the files; agent-delete removes the :Agent node and its owned knowledge projections before the directory and refuses the admin agent — writing these files by hand reaches none of those checks, which is what left an agent on disk and absent from the graph for a day), agent-image, plugin-toggle-enabled, premium-list, premium-deliver, skill-find, logs-read, cpu-triage-start and cpu-triage-read (the two-call device CPU diagnostic — start spawns a detached sampling run across at least one full 120s reconcile cycle and returns a run handle immediately, read returns running/complete/failed with the per-core distribution; no admin tool blocks through a sampling window, and no spot reading is obtainable), plugin-read, skill-load (one-call resolve+read for SKILL.md by skill name, the canonical primitive for loading a named skill; plugin-read remains the reader for references/* and PLUGIN.md), skill-search (free-text intent → skill resolver: ranks every plugin skill's SKILL.md name+description against a query and returns the top owners with their canonical skills/<slug>/ path, so intent→skill mapping survives the available-skills menu leaving context after a compaction), store-skill (deterministic write counterpart to plugin-read; persists operator-authored skills as plugin files under the active account), session-reset, session-resume, wifi, and action-approval tools (action-pending, action-approve, action-reject, action-edit) for managing the Real Agent platform."
+description: "Platform administration plugin. Provides system-status, public-hostname (deterministic Cloudflare public-URL resolver, single call returning the operator's canonical hostname so agents never guess property names on :CloudflareHostname nodes), admin-hostname (the admin-host twin of public-hostname — resolves the host that serves /calendar and the rest of the admin shell behind sign-in from the same ingress + alias + operator files, so agents point the operator at the admin /calendar URL instead of the public host that 404s it), publish-site (move an extracted static-site tree under <accountDir>/sites/<slug>/, emit one canonical path slug, and refresh llms.txt at the site root — typed refusal taxonomy replaces the prior skill-prose contract), brand-settings, account-manage, capabilities-here (deterministic install-introspection — returns enabledPlugins, tier, models, installed platform + premium specialists, registered Claude Code agent types, and the brand block as a single JSON object; the canonical tool for grounding any claim about what is enabled on the current account), linkedin-ingest-token (returns the account's durable LinkedIn ingest token — the one credential the Real Agent LinkedIn Ingest Chrome extension needs in its options page; minted on first call then stable across restarts and new chat sessions, and never a conversation session key nor the admin browser's session_key, which the ingest route rejects; action='rotate' replaces it and invalidates every existing extension install), account-update, the multi-account managed-service lifecycle tools (account_list, account_create, account_delete, account_purge, account_channel_routing, account_channel_routing_set — one Rubytech operator hosting N client accounts on one house install; create/delete/purge are operator-only and purge is two-step with a typed confirmation; account_create requires the client business owner's real name (ownerName), refusing a blank or the placeholder "Owner" and seeding it onto the sub-account's owner AdminUser and owner Person, and requires the owner's IANA timezone (timezone) — refusing a blank or a non-IANA value — seeding it onto the owner UserProfile marked owner-set so scheduling reads the owner's real zone from the start rather than the box's server default, while a managing house admin (its userId) is optional — when supplied it is validated as a live house admin and recorded as the sub-account's managingAdminUserId, and when omitted the sub-account is unmanaged and its passive-intake tasks route to the install's primary admin; account_reassign_admin repoints a client sub-account's managing admin to another live house admin (the repair path for a dangling managingAdminUserId, or to record one on an unmanaged account); account_roster is the canonical per-account identity view — one row per sub-account giving business name, role, the managing house admin resolved to a name with status (assigned/absent/dangling), the business owner from the graph with status (named/nameless), and the WhatsApp account-manager binding if any, each field carrying what it means and does not (managing admin is the responsible house team member not the owner; account manager is WhatsApp routing only with no admin rights), so the agent never stitches admin-list + account.json + whatsapp-config; account_set_owner_name names (or corrects) a client sub-account's business owner by writing the owned Person — the canonical name source — refusing a blank or the placeholder "Owner", the guarded repair for a nameless owner (the standing identity-audit op=nameless-owned-person detector); account_channel_routing_set repoints the house-paired WhatsApp/Telegram inbound stream to a different sub-account, and does not affect a sub-account's own separately paired WhatsApp number), admin-add (refuses on a client sub-account, where admin access is already install-wide so a per-operator seat grants nothing — the sub-account's one identity, its business owner, is set at account creation; the house account, where operators hold PIN logins and admins[] rows, is unchanged), admin-remove (refuses to remove a house admin who still manages one or more client sub-accounts, naming them so the operator reassigns each with account_reassign_admin first — never silently orphans them), admin-list, admin-update-pin, admin-bind (sets the phone and/or Telegram chat id on an admin's users.json entry — the binding resolveAdminUserId reads; without it a channel turn from that person resolves to no admin and the answer reaches only the door it arrived on, while a new admin is born bound by passing the same fields to admin-add. Defaults to the calling admin and routes an explicit userId through the same cross-identity gate the PIN tools use, requiring confirm=true, because a binding decides whose identity an inbound resolves to), agent-list, agent-config-read, the public-agent write tools (agent-create is the only supported way to create a public agent: it validates the slug against the same rule the router serves by, validates config.json against the servable schema, refuses an empty KNOWLEDGE, writes the four files with IDENTITY.md copied verbatim from the platform template, and projects the agent into the graph in the same call, reporting the verified projected count rather than assuming it; agent-update applies the same validation to a merged config, writes only the fields supplied, and re-projects, so the graph cannot fall behind the files; agent-delete removes the :Agent node and its owned knowledge projections before the directory and refuses the admin agent — writing these files by hand reaches none of those checks, which is what left an agent on disk and absent from the graph for a day), agent-image, plugin-toggle-enabled, premium-list, premium-deliver, skill-find, logs-read, cpu-triage-start and cpu-triage-read (the two-call device CPU diagnostic — start spawns a detached sampling run across at least one full 120s reconcile cycle and returns a run handle immediately, read returns running/complete/failed with the per-core distribution; no admin tool blocks through a sampling window, and no spot reading is obtainable), plugin-read, skill-load (one-call resolve+read for SKILL.md by skill name, the canonical primitive for loading a named skill; plugin-read remains the reader for references/* and PLUGIN.md), skill-search (free-text intent → skill resolver: ranks every plugin skill's SKILL.md name+description against a query and returns the top owners with their canonical skills/<slug>/ path, so intent→skill mapping survives the available-skills menu leaving context after a compaction), store-skill (deterministic write counterpart to plugin-read; persists operator-authored skills as plugin files under the active account), session-reset, session-resume, wifi, and action-approval tools (action-pending, action-approve, action-reject, action-edit) for managing the Real Agent platform."
 account-owned-files: [{"file": "webchat-channel-bindings.json", "description": "Routes this account's inbound admin webchat messages. Written by the session manager's webchat-channel-store."}, {"file": "wa-channel-bindings.json", "description": "Routes this account's inbound WhatsApp messages. Written by the session manager's wa-channel-store, which runs on every brand whether or not the whatsapp plugin ships."}, {"file": "telegram-channel-bindings.json", "description": "Routes this account's inbound Telegram messages. Written by the session manager's telegram-channel-store, which runs on every brand whether or not the telegram plugin ships."}, {"file": "canonical-webchat-session.json", "description": "Pins the account's canonical webchat session. Written by the admin UI server."}, {"file": "session-titles.json", "description": "Operator renames of sessions. Written by the session manager's title stores."}, {"file": "agents-disabled.json", "description": "Names the agents the operator switched off. Written by the admin agents route; provision reads it to re-apply the disables and never creates it."}]
 tools:
   - name: system-status
@@ -92,6 +92,10 @@ tools:
     publicAllowlist: false
     adminAllowlist: true
     riskClass: write_local
+  - name: admin-bind
+    publicAllowlist: false
+    adminAllowlist: true
+    riskClass: write_local
   - name: agent-list
     publicAllowlist: false
     adminAllowlist: true
@@ -225,7 +229,7 @@ Tools are available via the `admin` MCP server.
 
 **Client sub-accounts carry one owner identity, no operator seats.** Since admin access is install-wide (`canAccessAdmin` never reads `admins[]`), so `admin-add` on a `role:'client'` sub-account refuses before any store write and logs `[admin-add] op=refused-on-client reason=install-wide-access-no-seat account=<id8>`; only the house account seats admins. A standing session-manager audit (`redundant-operator-seat-audit.ts`) flags any pre-fix non-owner `AdminUser` on a client account with `[identity-audit] op=redundant-operator-seat`; removal of a flagged seat is a deliberate remediation, never automatic. See `.docs/admin-identity-surface.md`.
 
-**Three-store admin auth invariant.** `admin-add` (on the house account) writes to all three identity stores (`users.json` PIN auth at the persistent `~/{configDir}/users.json` location , `account.json` `admins[]` role, Neo4j `:AdminUser`/`:Person` graph identity) with per-leg `[admin-auth-store]` log lines plus the `[admins-write]` chokepoint line, and returns `is_error: true` on any leg failure naming what's already written. `admin-update-pin` writes `users.json` only and emits the same `[admin-auth-store]` line. **Single chokepoint:** every `users.json` + `account.json admins[]` mutation routes through `platform/lib/admins-write` (`writeAdminEntry` for admin-add/set-pin, `removeAdminFromAccount` for admin-remove); the static check `grep -rnE 'admins\.push\|config\.admins\s*=' platform/ \| grep -v lib/admins-write` returns 0. Direct `Edit`/`Write` on `account.json` is forbidden by IDENTITY.md doctrine — mutations go through `account-update`, `plugin-toggle-enabled`, or the `admin-*` tools. **Install + boot invariants:** the installer and admin-server boot walk every account.json admins[] vs users.json; `[install-invariant]` / `[admin-invariant] direction=… userId=<id8> source=<file>` fires per divergence with a `check complete divergences=<n>` summary. Log-only — does not block. See `.docs/agents.md` § "Three-store admin auth invariant" for the full contract.
+**Three-store admin auth invariant.** `admin-add` (on the house account) writes to all three identity stores (`users.json` PIN auth at the persistent `~/{configDir}/users.json` location , `account.json` `admins[]` role, Neo4j `:AdminUser`/`:Person` graph identity) with per-leg `[admin-auth-store]` log lines plus the `[admins-write]` chokepoint line, and returns `is_error: true` on any leg failure naming what's already written. `admin-update-pin` writes `users.json` only and emits the same `[admin-auth-store]` line. **Single chokepoint:** every `users.json` + `account.json admins[]` mutation routes through `platform/lib/admins-write` (`writeAdminEntry` for admin-add/set-pin/admin-bind, `removeAdminFromAccount` for admin-remove); the static check `grep -rnE 'admins\.push\|config\.admins\s*=' platform/ \| grep -v lib/admins-write` returns 0. Direct `Edit`/`Write` on `account.json` is forbidden by IDENTITY.md doctrine — mutations go through `account-update`, `plugin-toggle-enabled`, or the `admin-*` tools. **Install + boot invariants:** the installer and admin-server boot walk every account.json admins[] vs users.json; `[install-invariant]` / `[admin-invariant] direction=… userId=<id8> source=<file>` fires per divergence with a `check complete divergences=<n>` summary. Log-only — does not block. See `.docs/agents.md` § "Three-store admin auth invariant" for the full contract.
 
 **Credential audit trail (append-only).** Every write to the credential stores emits one canonical `[users-audit] action=<set-access|clear-access|add|remove|set-pin|migrate> actor=<id8|onboarding|install|boot|unknown> [session=<id8>] field=<accessHash|pin|row> rowsBefore=<id8,…> rowsAfter=<id8,…> ts=<iso>` line to `~/{configDir}/logs/users-audit.log` — a dedicated file, distinct from `server.log`, so a credential mutation is greppable in isolation. The line is emitted at the writer chokepoint (`admin-access-password` for accessHash set/clear/migrate, `admins-write` `writeAdminEntry`/`removeAdminFromAccount` for row/pin/role) so every caller is covered; the one direct users.json writer that does not route through `writeAdminEntry` — `admin-update-pin` — emits the same line via the exported `logUsersAudit`. A write that changes no field (a clear with no hash, a migrate noop, an absent-admin remove) emits nothing. Credential-mutating MCP tools add `session=<id8>` from `SESSION_NODE_ID` so a mutation traces to its agent session even when the transcript is gone.
 
@@ -272,8 +276,9 @@ Tools are available via the `admin` MCP server.
 - `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/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/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. **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. **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.
 - `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_settings` (`platform/scripts/lib/account-settings-reconcile.sh`) on every install, converging every existing account's `settings.json` against `platform/templates/account-settings.json` — which carries this matcher — with one `[settings-reconcile] account=<id> status=<already-set|updated|absent-seeded|rewrite-failed|no-template>` line per account and one `[settings-reconcile] accounts=<n> divergent=<n>` summary, contents never echoed. (The per-hook backfill lib this converge replaced has been retired.)

package/payload/platform/plugins/admin/hooks/__tests__/html-structure-gate.test.sh

@@ -0,0 +1,264 @@
+#!/usr/bin/env bash
+# Regression test for html-structure-gate.sh.
+#
+# A second <style> opener nested inside an open <style> element is not a
+# cosmetic fault. 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 on the page, and the rule immediately after the stray opener is
+# eaten as part of an invalid selector. One fault, two symptoms, and a client
+# quotation went out carrying both.
+#
+# The gate walks the document the call would PRODUCE, not the fragment it
+# carries. For Write that is `content`; for Edit and MultiEdit the on-disk file
+# is read and the replacements applied in memory first. Walking a fragment cannot
+# work: the unbalanced-at-EOF rule would refuse every partial edit, and a nested
+# opener whose outer <style> is already on disk would pass.
+#
+# Scope is the whole account with an exclusion list, never a bucket list. A
+# bucket list is what let the live file through: it sat under sites/<project>/
+# public/, which no quote bucket covers.
+#
+# Covers:
+#   A. Write producing a nested opener            → BLOCKED, names the line
+#   B. the same document with the opener removed  → ALLOWED
+#   C. <style> inside an HTML comment             → ALLOWED
+#   D. three openers, two closers                 → BLOCKED, names the unmatched one
+#   E. a write under sites/<project>/public/      → BLOCKED (not a quote bucket)
+#   F. a write under node_modules/                → ALLOWED (excluded)
+#   G. a .txt target                              → ALLOWED
+#   H. Edit introducing the opener into a clean file → BLOCKED
+#   I. Edit elsewhere in an already-malformed file   → BLOCKED
+#   J. MultiEdit whose second edit introduces it     → BLOCKED
+#   K. empty stdin                                → ALLOWED (fail-open)
+#   L. a Read of a malformed path                 → ALLOWED
+#   M. a path outside the account dir             → ALLOWED
+#   N. a block appends the op=refuse line, path JSON-quoted
+
+set -u
+
+HOOK="$(cd "$(dirname "$0")/.." && pwd)/html-structure-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/2078cb54abcd"
+mkdir -p "$ACCT/sites/gls-sign/public" "$ACCT/node_modules/pkg" "$ACCT/logs" \
+         "$ACCT/documents/Quotations/1867" "$FAKE/outside"
+
+# A document whose stray opener sits at line 4.
+NESTED='<html>
+<style>
+:root{--orange:#F89828;}
+<style>
+  .esign-box{border:1px solid var(--orange);}
+</style>
+<body>ok</body>
+</html>'
+
+CLEAN='<html>
+<style>
+:root{--orange:#F89828;}
+  .esign-box{border:1px solid var(--orange);}
+</style>
+<body>ok</body>
+</html>'
+
+# The false positive a comment-blind detector produces: the templates on the
+# live install carry a <style> inside an HTML comment and are clean.
+COMMENTED='<html>
+<style>
+a{}
+<!--
+<style>
+-->
+</style>
+</html>'
+
+# Three openers, two closers. The unmatched opener is on line 5.
+UNBALANCED='<style>
+</style>
+<style>
+</style>
+<style>
+a{}'
+
+# Already malformed on disk: an edit anywhere in it still produces a malformed
+# document, so it is refused.
+printf '%s\n' "$NESTED" > "$ACCT/documents/Quotations/1867/broken.html"
+printf '%s\n' "$CLEAN" > "$ACCT/documents/Quotations/1867/clean.html"
+printf '%s\n' "$NESTED" > "$FAKE/outside/broken.html"
+
+PASS=0
+FAIL=0
+
+write_envelope() { # file_path, content
+  python3 -c '
+import json, sys
+print(json.dumps({"hook_event_name": "PreToolUse", "tool_name": "Write",
+                  "tool_input": {"file_path": sys.argv[1], "content": sys.argv[2]}}))' "$1" "$2"
+}
+
+edit_envelope() { # file_path, old_string, new_string
+  python3 -c '
+import json, sys
+print(json.dumps({"hook_event_name": "PreToolUse", "tool_name": "Edit",
+                  "tool_input": {"file_path": sys.argv[1], "old_string": sys.argv[2],
+                                 "new_string": sys.argv[3]}}))' "$1" "$2" "$3"
+}
+
+multiedit_envelope() { # file_path, old1, new1, old2, new2
+  python3 -c '
+import json, sys
+print(json.dumps({"hook_event_name": "PreToolUse", "tool_name": "MultiEdit",
+                  "tool_input": {"file_path": sys.argv[1], "edits": [
+                      {"old_string": sys.argv[2], "new_string": sys.argv[3]},
+                      {"old_string": sys.argv[4], "new_string": sys.argv[5]}]}}))' "$1" "$2" "$3" "$4" "$5"
+}
+
+other_envelope() { # tool_name, file_path
+  python3 -c '
+import json, sys
+print(json.dumps({"hook_event_name": "PreToolUse", "tool_name": sys.argv[1],
+                  "tool_input": {"file_path": sys.argv[2]}}))' "$1" "$2"
+}
+
+run_case() { # name, stdin, expected_exit
+  local name="$1" stdin="$2" expected_exit="$3" actual_exit
+  ( cd "$ACCT" && export LOG_DIR="$ACCT/logs" && 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
+}
+
+run_line_case() { # name, stdin, expected_line
+  local name="$1" stdin="$2" want="$3" out
+  out=$( cd "$ACCT" && export LOG_DIR="$ACCT/logs" && printf '%s' "$stdin" | bash "$HOOK" 2>&1 >/dev/null )
+  if printf '%s' "$out" | grep -q "line $want"; then
+    echo "PASS: $name (names line $want)"
+    PASS=$((PASS + 1))
+  else
+    echo "FAIL: $name (expected line $want, got: $out)" >&2
+    FAIL=$((FAIL + 1))
+  fi
+}
+
+run_case "A: Write producing a nested opener → BLOCKED" \
+  "$(write_envelope 'documents/Quotations/1867/new.html' "$NESTED")" 2
+
+run_line_case "A2: the block names the stray opener's line" \
+  "$(write_envelope 'documents/Quotations/1867/new.html' "$NESTED")" 4
+
+run_case "B: the same document with the opener removed → ALLOWED" \
+  "$(write_envelope 'documents/Quotations/1867/new.html' "$CLEAN")" 0
+
+run_case "C: <style> inside an HTML comment → ALLOWED" \
+  "$(write_envelope 'documents/Quotations/1867/front-matter.html' "$COMMENTED")" 0
+
+run_case "D: three openers, two closers → BLOCKED" \
+  "$(write_envelope 'documents/Quotations/1867/new.html' "$UNBALANCED")" 2
+
+run_line_case "D2: the unbalanced block names the unmatched opener" \
+  "$(write_envelope 'documents/Quotations/1867/new.html' "$UNBALANCED")" 5
+
+run_case "E: a write under sites/<project>/public/ → BLOCKED" \
+  "$(write_envelope 'sites/gls-sign/public/quote-gresswell.html' "$NESTED")" 2
+
+run_case "F: a write under node_modules/ → ALLOWED (excluded)" \
+  "$(write_envelope 'node_modules/pkg/broken.html' "$NESTED")" 0
+
+run_case "G: a .txt target → ALLOWED" \
+  "$(write_envelope 'documents/Quotations/1867/notes.txt' "$NESTED")" 0
+
+run_case "H: Edit introducing the opener into a clean file → BLOCKED" \
+  "$(edit_envelope 'documents/Quotations/1867/clean.html' '  .esign-box' '<style>
+  .esign-box')" 2
+
+run_case "I: Edit elsewhere in an already-malformed file → BLOCKED" \
+  "$(edit_envelope 'documents/Quotations/1867/broken.html' '<body>ok</body>' '<body>changed</body>')" 2
+
+run_case "J: MultiEdit whose second edit introduces the opener → BLOCKED" \
+  "$(multiedit_envelope 'documents/Quotations/1867/clean.html' '<body>ok</body>' '<body>two</body>' '  .esign-box' '<style>
+  .esign-box')" 2
+
+# The shipped property-brochure template documents its override slot with a CSS
+# comment naming the tag it wants emitted. The CSS parser discards a comment, so
+# the mention is inert. A closer is NOT protected the same way: style content is
+# raw text to the HTML parser, so </style> terminates the element wherever it
+# appears.
+CSS_COMMENT='<html>
+<style>
+a{}
+/* branded register MUST emit a <style id="brand-tokens"> block here */
+b{}
+</style>
+</html>'
+
+CLOSER_IN_COMMENT='<html>
+<style>
+a{}
+/* </style> */
+<style>
+<style>
+</style>
+</html>'
+
+run_case "K: empty stdin → ALLOWED (fail-open)" "" 0
+
+run_case "K2: an opener named inside a CSS comment → ALLOWED" \
+  "$(write_envelope 'documents/Quotations/1867/brochure.html' "$CSS_COMMENT")" 0
+
+run_case "K3: a closer inside a CSS comment still closes, so the next nesting is caught" \
+  "$(write_envelope 'documents/Quotations/1867/brochure.html' "$CLOSER_IN_COMMENT")" 2
+
+run_case "L: a Read of a malformed path → ALLOWED" \
+  "$(other_envelope Read 'documents/Quotations/1867/broken.html')" 0
+
+run_case "M: a path outside the account dir → ALLOWED" \
+  "$(write_envelope "$FAKE/outside/broken.html" "$NESTED")" 0
+
+# N. The observability line: one append per refusal, path JSON-quoted so a
+# filename carrying spaces survives a key=value reader.
+SPACED='documents/Quotations/1867/Q1867 - 22 Barley Ponds Road (Themistocli).html'
+( cd "$ACCT" && export LOG_DIR="$ACCT/logs" && printf '%s' "$(write_envelope "$SPACED" "$NESTED")" | bash "$HOOK" >/dev/null 2>&1 )
+if grep -qF '[html-structure-gate] op=refuse account=2078cb54 file="documents/Quotations/1867/Q1867 - 22 Barley Ponds Road (Themistocli).html" line=4' "$ACCT/logs/server.log" 2>/dev/null; then
+  echo "PASS: N: the refusal is logged with a JSON-quoted path and the account id8"
+  PASS=$((PASS + 1))
+else
+  echo "FAIL: N: no op=refuse line (got: $(cat "$ACCT/logs/server.log" 2>/dev/null))" >&2
+  FAIL=$((FAIL + 1))
+fi
+
+# O. Brand isolation: when no brand-correct sink resolves, the refusal still
+# blocks but writes nothing. Four brands are co-resident on the laptop and each
+# has its own ~/.<brand>/logs, so a hard-coded fallback would file one brand's
+# account path in another brand's server.log.
+BARE="$FAKE/accounts/bare0000acct"
+mkdir -p "$BARE"
+printf '%s\n' "$NESTED" > "$BARE/doc.html"
+FAKEHOME="$FAKE/fakehome"
+mkdir -p "$FAKEHOME/.maxy-code/logs"
+O_ENVELOPE=$(write_envelope 'doc.html' "$NESTED")
+( cd "$BARE" && printf '%s' "$O_ENVELOPE" | env -u LOG_DIR -u CLAUDE_SESSION_MANAGER_PERSIST_DIR \
+    HOME="$FAKEHOME" bash "$HOOK" >/dev/null 2>&1 )
+O_EXIT=$?
+if [[ "$O_EXIT" -eq 2 ]] && [[ ! -s "$FAKEHOME/.maxy-code/logs/server.log" ]]; then
+  echo "PASS: O: with no brand-correct sink the write is still refused and no other brand's log is written"
+  PASS=$((PASS + 1))
+else
+  echo "FAIL: O: exit=$O_EXIT, foreign log=$(cat "$FAKEHOME/.maxy-code/logs/server.log" 2>/dev/null)" >&2
+  FAIL=$((FAIL + 1))
+fi
+
+echo "──────── html-structure-gate test summary ────────"
+echo "PASS=$PASS FAIL=$FAIL"
+[[ "$FAIL" -eq 0 ]]