@rubytech/create-realagent-code 0.1.568 → 0.1.570

package/payload/platform/plugins/admin/skills/whats-new/SKILL.md

@@ -9,6 +9,20 @@ Invoked by the admin agent directly.
 
 This is the platform's release timeline, newest first. Each entry shows the date it shipped and the version it shipped in, so you can tell the operator how current their install is. To compare, read the installed version from `capabilities-here` and match it against the versions below. Keep answers high level and in plain English; this is a summary, not a full commit log.
 
+## 2026-08-06 (0.1.570)
+
+- Reading a PDF now injects the text layer, so values copied from a PDF are not transcribed by eye any more.
+- The four one-hook account-settings backfill libs have been retired; hook registration is now driven from the account-settings template.
+- The operator is now notified when a tool call stays blocked, with a per-account census, and the notification is scoped to the blocked session's own account.
+
+## 2026-08-06 (0.1.569)
+
+- Every account's safeguards are now brought up to date on each install. They used to be written once when the account was created and never revisited, so an account could be missing a protection that every other account had, with nothing reporting the gap.
+- A customer quote can now only be produced by the specialist that owns it. Other assistants were writing quote documents by hand, bypassing the template and the renderer entirely; writes to a quote from anything else are now refused, including producing the PDF through the shell.
+- A specialist you wrote for your own account is dispatchable again. The roster was matching on filenames rather than the name declared inside the file, so cards that looked registered could not actually be reached and the work fell to a general-purpose assistant instead.
+- Two new standing checks: one counts work written into an owned area by the wrong specialist, the other reconciles quotes that were sent against the records of what was actually rendered.
+- A quote's running header no longer depends on where the author happened to put page breaks, so it appears on every page rather than the ones that were hand-marked.
+
 ## 2026-08-06 (0.1.568)
 
 - Answers reach the conversation they came from again. An answer was being routed by who the account's admin is rather than by the conversation it was sent to, so a public agent's reply could go nowhere and an admin answer could strand with nothing said about it. Delivery now returns to the door the message arrived on, and every failure to find one is named rather than passing silently. If you rolled an install back because of this, you can move forward again.

package/payload/platform/plugins/docs/references/admin-session.md

@@ -182,6 +182,21 @@ grep -E "\[(pty-spawn-tool-inventory|recorder-session-init|recorder-turn|mcp:(me
 
 **Loopback gate.** The `/api/admin/log-ingest` route is loopback-only on both the socket address and (when present) the `X-Forwarded-For` header. A LAN client whose request reaches the route via a proxy still gets a 403 because XFF tokens are required to be loopback when XFF is set. Without this gate the evidence chain would be worthless — any LAN client could forge `[recorder-session-init]` lines under a spoofed sessionId.
 
+## A session that stopped with the PTY alive
+
+Claude Code raises a permission card for some checks even under `permissionMode=bypassPermissions`: `dangerousRemoval` is `bypassImmune: true` in its safety table, so no allow rule and no permission mode pre-approves it. When such a card is raised inside a background subagent, its only prompt surface is the parent session's UI, so an operator on WhatsApp or Telegram cannot see or answer it and the session simply stops.
+
+The manager's blocked-tool census reconciles this against live state every 60s. It reads a bounded tail of each live session's own transcript and of every `<sessionId>/subagents/agent-*.jsonl`, and treats an assistant `tool_use` with no matching `tool_result` as blocked once that transcript has not advanced for 120s. Three line shapes, all under `[blocked-tool]`:
+
+- `op=census sessions=<n> scanned=<n> blocked=<n>` — every tick, including zero. A gap in this line means the census stopped, not that nothing was blocked. `sessions` counts live PTYs and `scanned` counts transcripts actually read, so `sessions=3 scanned=0` means no transcript could be resolved for any live session, which is a fault rather than a quiet box.
+- `op=blocked sessionId=<id8> agentId=<id> toolUseId=<id> tool=<name> blockedForMs=<n>` — once per blocked call. `agentId=—` means the card is in the session's own transcript, where the operator can see it in the session UI; `agent-<id>` means it is inside that background subagent, where they cannot. `blockedForMs` is the age of the transcript's last record, not a timer on the call.
+- `op=cleared` with the same ids, once the result lands on a still-live session.
+- `op=session-gone` with the same ids when the session stopped being live with the card still unanswered. This is deliberately not `op=cleared`: the call never resolved, and conflating the two would read as "the block lifted".
+
+At 180s blocked the manager sends one notification through the loopback route `/api/admin/session-blocked`, which is gated the same way as `log-ingest`. `op=blocked-notify channel=<name> delivered=<bool>` records where it went and whether it landed. `channel=whatsapp` or `telegram` means the session's own admin door; `channel=house-admin` means the house admin phones, which is what a public session always gets — a public session's own channel is a customer and never receives internal machinery. `delivered=false` with `channel=none` means the manager could not reach the route at all.
+
+The notification cannot answer the card. Answer it in the session's PTY or in Claude Desktop.
+
 ## Out of scope
 
 - Public/WhatsApp/Telegram sessions — out of scope. Their sessionKeys remain `crypto.randomUUID()` and follow the existing rejection-on-restart contract.

package/payload/platform/scripts/__tests__/mailbox-inject-registered.test.sh

@@ -1,32 +1,26 @@
 #!/usr/bin/env bash
-# Task 2157 — the hook must be registered in BOTH writers, with the SAME resolved
-# command string. The provision-time heredoc is a frequent merge-conflict site,
-# and the backfill lib is the only thing that reaches client sub-accounts, so
-# losing either is silent. Drift between the two is worse than losing one: the
-# backfill would not recognise what provision wrote, and would append a second
-# copy to every house account on every install.
+# Task 2157 — the hook must be registered in the account-settings template, in
+# the UserPromptSubmit event, with a fully resolved command path. The template
+# is the single writer since Task 2467, and Task 2475 retired the backfill lib
+# that used to be the second one, so losing the entry here loses it everywhere.
 #
-# Substring greps are deliberately avoided for the command itself: the lib's own
-# filename contains "mailbox-inject.sh", so a bare grep for that is satisfied by
-# a comment and proves nothing about what the lib would write.
+# Substring greps are deliberately avoided for the command itself: a bare grep
+# for "mailbox-inject.sh" is satisfied by a comment and proves nothing about
+# what would be written.
 set -uo pipefail
 DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-PROV="$DIR/../lib/provision-account-dir.sh"
-BACKFILL="$DIR/../lib/account-settings-mailbox-inject.sh"
-SETUP="$DIR/../setup-account.sh"
+PROV="$DIR/../../templates/account-settings.json"
 PASS=0; FAIL=0
 
 ok()  { echo "PASS: $1"; PASS=$((PASS+1)); }
 bad() { echo "FAIL: $1" >&2; FAIL=$((FAIL+1)); }
 
-# What provision-account-dir.sh writes into the settings heredoc. HOOKS_PATH is
-# assigned there as the literal string $PLATFORM_ROOT/plugins/admin/hooks, so the
-# resolved command is the same string the backfill lib holds.
-PROV_LINE='{ "type": "command", "command": "bash $HOOKS_PATH/mailbox-inject.sh" }'
-RESOLVED='bash $PLATFORM_ROOT/plugins/admin/hooks/mailbox-inject.sh'
+# The exact line the template must carry. $PLATFORM_ROOT is a literal in the
+# settings file, resolved by Claude Code at hook-run time.
+PROV_LINE='{ "type": "command", "command": "bash $PLATFORM_ROOT/plugins/admin/hooks/mailbox-inject.sh" }'
 
 if /usr/bin/grep -qF "$PROV_LINE" "$PROV"; then
-  ok "provision-account-dir.sh writes the hook into a UserPromptSubmit entry"
+  ok "the template writes the hook into a UserPromptSubmit entry"
 else
   bad "exact provision command line absent from $PROV"
 fi
@@ -44,36 +38,18 @@ else
   bad "mailbox-inject.sh is not inside the UserPromptSubmit array in $PROV"
 fi
 
-# The backfill lib must hold the RESOLVED form of that same command.
-if /usr/bin/grep -qF "_MBXINJECT_CMD='$RESOLVED'" "$BACKFILL"; then
-  ok "the backfill lib writes the same resolved command string"
+# The command must be fully resolved in the template. An unresolved HOOKS_PATH
+# indirection would leave the path to be expanded by whoever copies the file,
+# and the account would carry a hook command that resolves to nothing.
+if ! /usr/bin/grep -q 'HOOKS_PATH' "$PROV"; then
+  ok "the template carries no unresolved hook-path indirection"
 else
-  bad "backfill _MBXINJECT_CMD is not '$RESOLVED' in $BACKFILL"
-fi
-
-# HOOKS_PATH must still resolve to the path the backfill lib assumes; if someone
-# repoints it, the two writers silently disagree and every account gets two hooks.
-if /usr/bin/grep -qF 'HOOKS_PATH="\$PLATFORM_ROOT/plugins/admin/hooks"' "$PROV"; then
-  ok "HOOKS_PATH resolves to the path the backfill lib assumes"
-else
-  bad "HOOKS_PATH in $PROV no longer matches the backfill lib assumption"
-fi
-
-if /usr/bin/grep -qF 'account-settings-mailbox-inject.sh' "$SETUP"; then
-  ok "backfill lib sourced by setup-account.sh"
-else
-  bad "backfill lib not sourced by $SETUP"
-fi
-
-if /usr/bin/grep -qE '^reconcile_all_accounts_mailbox_inject "\$ACCOUNTS_DIR"' "$SETUP"; then
-  ok "backfill invoked over every account by setup-account.sh"
-else
-  bad "reconcile_all_accounts_mailbox_inject not invoked in $SETUP"
+  bad "$PROV still carries a HOOKS_PATH indirection, so the written command would not resolve"
 fi
 
 echo "----"
 echo "PASS=$PASS FAIL=$FAIL"
-if [ $((PASS+FAIL)) -ne 6 ]; then
+if [ $((PASS+FAIL)) -ne 3 ]; then
   echo "FAIL: expected 6 checks, ran $((PASS+FAIL))" >&2
   exit 1
 fi

package/payload/platform/scripts/__tests__/preference-hooks-registered.test.sh

@@ -1,7 +1,9 @@
 #!/usr/bin/env bash
 set -uo pipefail
 DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-LIB="$DIR/../lib/provision-account-dir.sh"
+# The provision-time source of the hook set is the template provision_account_dir
+# copies verbatim, not a heredoc inside the writer.
+LIB="$DIR/../../templates/account-settings.json"
 PASS=0; FAIL=0; FAILED=()
 c(){ if grep -qF "$1" "$LIB"; then PASS=$((PASS+1)); else FAIL=$((FAIL+1)); FAILED+=("$2"); fi; }
 c 'preference-consult-gate.sh' "gate registered"

package/payload/platform/scripts/__tests__/public-prompt-gate-registered.test.sh

@@ -4,12 +4,12 @@
 # event and does not reproduce on demand: the only symptom is a stranger being
 # told something about the operator.
 #
-# Both writers are scanned. provision-account-dir.sh writes the array at account
-# creation; the account-settings-*.sh libs patch it onto accounts that already
-# exist, which is the only path that reaches client sub-accounts. Of the four
-# libs only mailbox-inject and public-surface touch this event — askgate patches
-# PreToolUse and pdf-conformance patches PostToolUse, so the filter skipping
-# them is correct rather than a broken parser.
+# The template is the single writer: provision-account-dir.sh copies
+# platform/templates/account-settings.json at account-creation time, and
+# setup-account.sh's reconcile_all_accounts_settings converges every existing
+# account against the same file on every install. Task 2475 retired the four
+# one-hook backfill libs that used to patch this array, so the template is the
+# only place a UserPromptSubmit hook can be registered.
 #
 # The guard is matched as a fixed string, never as a mention of the variable: a
 # hook that merely READS MAXY_PUBLIC_ALLOWED_TOOLS is not gated by it, and
@@ -17,6 +17,7 @@
 set -uo pipefail
 DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 PROV="$DIR/../lib/provision-account-dir.sh"
+TPL="$DIR/../../templates/account-settings.json"
 HOOKS_DIR="$DIR/../../plugins/admin/hooks"
 GUARD='[ -n "${MAXY_PUBLIC_ALLOWED_TOOLS:-}" ]'
 INERT="archive-ingest-surface-gate.sh public-tool-surface.sh"
@@ -25,44 +26,28 @@ PASS=0; FAIL=0
 ok()  { echo "PASS: $1"; PASS=$((PASS+1)); }
 bad() { echo "FAIL: $1" >&2; FAIL=$((FAIL+1)); }
 
-# Every hook script named inside the provision heredoc's UserPromptSubmit array.
-# The script name is taken from the END of each `"command"` string, not from a
-# `hooks/` prefix: provision writes `bash $HOOKS_PATH/<name>.sh`, so the literal
-# directory never appears there and a prefix anchor silently matches nothing.
-PROV_HOOKS=$(python3 - "$PROV" <<'PY'
-import re, sys
-src = open(sys.argv[1], encoding="utf-8").read()
-m = re.search(r'"UserPromptSubmit"\s*:\s*\[(.*?)\n    \]', src, re.S)
-if not m:
-    print("")
-    sys.exit(0)
-cmds = re.findall(r'"command"\s*:\s*"([^"]*)"', m.group(1))
-names = [n.group(1) for n in (re.search(r'([A-Za-z0-9_.-]+\.sh)\s*$', c.strip()) for c in cmds) if n]
+# Every hook script named inside the template's UserPromptSubmit array. The
+# script name is taken from the END of each `"command"` string, not from a
+# `hooks/` prefix: the template writes `bash $PLATFORM_ROOT/plugins/admin/hooks/
+# <name>.sh`, and anchoring on a literal directory would break the first time
+# that prefix is spelled differently.
+TPL_HOOKS=$(python3 - "$TPL" <<'PY'
+import json, re, sys
+doc = json.load(open(sys.argv[1], encoding="utf-8"))
+cmds = [h.get("command", "")
+        for entry in doc.get("hooks", {}).get("UserPromptSubmit", [])
+        for h in entry.get("hooks", [])]
+names = [m.group(1) for m in (re.search(r'([A-Za-z0-9_.-]+\.sh)\s*$', c.strip()) for c in cmds) if m]
 print("\n".join(sorted(set(names))))
 PY
 )
 
-# Every hook script named by a backfill lib that patches the same array. Read
-# only from the `_<NAME>_CMD=` constant each lib registers, not from every `.sh`
-# in the file: these libs name their siblings in prose, and a bare `.sh` sweep
-# turns those comments into phantom registrations.
-BACKFILL_HOOKS=""
-for lib in "$DIR"/../lib/account-settings-*.sh; do
-  grep -q 'hooks\.UserPromptSubmit' "$lib" || continue
-  cmd_names=$(grep -oE "^_[A-Z0-9_]+_CMD='[^']*'" "$lib" | grep -oE "[A-Za-z0-9_.-]+\.sh'$" | tr -d "'")
-  if [ -z "$cmd_names" ]; then
-    bad "$(basename "$lib") patches UserPromptSubmit but names no _<NAME>_CMD script — the parser cannot see what it registers"
-  fi
-  BACKFILL_HOOKS="$BACKFILL_HOOKS
-$cmd_names"
-done
-
-ALL=$(printf '%s\n%s\n' "$PROV_HOOKS" "$BACKFILL_HOOKS" | grep -v '^$' | sort -u)
+ALL=$(printf '%s\n' "$TPL_HOOKS" | grep -v '^$' | sort -u)
 
 if [ -z "$ALL" ]; then
-  bad "no UserPromptSubmit hooks found in either writer — the parser is broken, not the tree"
+  bad "no UserPromptSubmit hooks found in the template — the parser is broken, not the tree"
 else
-  ok "found $(printf '%s\n' "$ALL" | wc -l | tr -d ' ') registered UserPromptSubmit hooks across both writers"
+  ok "found $(printf '%s\n' "$ALL" | wc -l | tr -d ' ') registered UserPromptSubmit hooks in the template"
 fi
 
 for h in $ALL; do

package/payload/platform/scripts/__tests__/public-surface-registered.test.sh

@@ -1,25 +1,20 @@
 #!/usr/bin/env bash
-# Task 2339 — the hook must be registered in BOTH writers, on BOTH events, with
-# the SAME resolved command string. The provision-time heredoc is a frequent
-# merge-conflict site and the backfill lib is the only thing that reaches client
-# sub-accounts, so losing either is silent. Drift between them is worse than
-# losing one: the backfill would not recognise what provision wrote and would
-# append a second copy to every house account on every install.
+# Task 2339 — the hook must be registered in the account-settings template, on
+# all three events, with a fully resolved command path. The template is the
+# single writer since Task 2467, and Task 2475 retired the backfill lib that
+# used to be the second one, so losing an entry here loses it everywhere.
 set -uo pipefail
 DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-PROV="$DIR/../lib/provision-account-dir.sh"
-BACKFILL="$DIR/../lib/account-settings-public-surface.sh"
-SETUP="$DIR/../setup-account.sh"
+PROV="$DIR/../../templates/account-settings.json"
 PASS=0; FAIL=0
 
 ok()  { echo "PASS: $1"; PASS=$((PASS+1)); }
 bad() { echo "FAIL: $1" >&2; FAIL=$((FAIL+1)); }
 
-PROV_LINE='{ "type": "command", "command": "bash $HOOKS_PATH/public-tool-surface.sh" }'
-RESOLVED='bash $PLATFORM_ROOT/plugins/admin/hooks/public-tool-surface.sh'
+PROV_LINE='{ "type": "command", "command": "bash $PLATFORM_ROOT/plugins/admin/hooks/public-tool-surface.sh" }'
 
 if [ "$(/usr/bin/grep -cF "$PROV_LINE" "$PROV")" = "3" ]; then
-  ok "provision-account-dir.sh writes the hook exactly three times"
+  ok "the template writes the hook exactly three times"
 else
   bad "expected 3 provision command lines in $PROV"
 fi
@@ -69,34 +64,16 @@ else
   bad "public-tool-surface.sh is not inside the UserPromptSubmit array in $PROV"
 fi
 
-if /usr/bin/grep -qF "_PUBSURFACE_CMD='$RESOLVED'" "$BACKFILL"; then
-  ok "the backfill lib writes the same resolved command string"
+if ! /usr/bin/grep -q 'HOOKS_PATH' "$PROV"; then
+  ok "the template carries no unresolved hook-path indirection"
 else
-  bad "backfill _PUBSURFACE_CMD is not '$RESOLVED' in $BACKFILL"
-fi
-
-if /usr/bin/grep -qF 'HOOKS_PATH="\$PLATFORM_ROOT/plugins/admin/hooks"' "$PROV"; then
-  ok "HOOKS_PATH resolves to the path the backfill lib assumes"
-else
-  bad "HOOKS_PATH in $PROV no longer matches the backfill lib assumption"
-fi
-
-if /usr/bin/grep -qF 'account-settings-public-surface.sh' "$SETUP"; then
-  ok "backfill lib sourced by setup-account.sh"
-else
-  bad "backfill lib not sourced by $SETUP"
-fi
-
-if /usr/bin/grep -qE '^reconcile_all_accounts_public_surface "\$ACCOUNTS_DIR"' "$SETUP"; then
-  ok "backfill invoked over every account by setup-account.sh"
-else
-  bad "reconcile_all_accounts_public_surface not invoked in $SETUP"
+  bad "$PROV still carries a HOOKS_PATH indirection, so the written command would not resolve"
 fi
 
 echo "----"
 echo "PASS=$PASS FAIL=$FAIL"
-if [ $((PASS+FAIL)) -ne 8 ]; then
-  echo "FAIL: expected 8 checks, ran $((PASS+FAIL))" >&2
+if [ $((PASS+FAIL)) -ne 5 ]; then
+  echo "FAIL: expected 5 checks, ran $((PASS+FAIL))" >&2
   exit 1
 fi
 [ "$FAIL" -eq 0 ]

package/payload/platform/scripts/__tests__/quote-ownership-contract.test.sh

@@ -0,0 +1,86 @@
+#!/usr/bin/env bash
+# The client quote document has exactly one owner, and that ownership is a
+# capability as well as a claim.
+#
+# A hand-orchestrated quote reached a customer because the quoter's own card
+# disclaimed document work ("not a document edit for another agent"), so the
+# admin's routing to a general content specialist was correct against it. The
+# guarantee that replaced that prose is a capability: the quote tools are
+# granted to the quoter's card and to no other, so no other agent can produce a
+# receipt-bearing quote by any route.
+#
+# Covers:
+#   A. the quoter's body claims ownership of the document's presentation
+#   B. the disclaimer that sent document work elsewhere is gone
+#   C. the description front-matter carries the same claim (the roster text the
+#      admin reads at dispatch time)
+#   D. quote-render / quote-engine-run are granted to the quoter
+#   E. no other card in the tree grants either tool
+
+set -u
+
+ROOT="$(cd "$(dirname "$0")/../../.." && pwd)"
+QUOTER="$ROOT/premium-plugins/sitedesk/agents/sitedesk--quoter.md"
+
+PASS=0
+FAIL=0
+ok()  { echo "PASS: $1"; PASS=$((PASS + 1)); }
+bad() { echo "FAIL: $1" >&2; FAIL=$((FAIL + 1)); }
+
+if [ ! -f "$QUOTER" ]; then
+  echo "FAIL: quoter card missing at $QUOTER" >&2
+  exit 1
+fi
+
+# Body = everything outside the frontmatter block.
+BODY="$(sed -n '/^---$/,/^---$/!p' "$QUOTER")"
+DESC="$(grep -m1 '^description:' "$QUOTER" || true)"
+
+for word in layout "cover page" photograph "running header" correction; do
+  if printf '%s' "$BODY" | grep -qi -- "$word"; then
+    ok "A: body claims $word"
+  else
+    bad "A: body does not claim $word"
+  fi
+done
+
+if grep -q 'not a document edit for another agent' "$QUOTER"; then
+  bad "B: the document-edit disclaimer is still present"
+else
+  ok "B: document-edit disclaimer absent"
+fi
+
+if printf '%s' "$DESC" | grep -qi 'owns the client quote document'; then
+  ok "C: description carries the ownership claim"
+else
+  bad "C: description does not carry the ownership claim"
+fi
+
+TOOLS="$(grep -m1 '^tools:' "$QUOTER" || true)"
+for t in quote-render quote-engine-run; do
+  if printf '%s' "$TOOLS" | grep -q -- "$t"; then
+    ok "D: quoter grants $t"
+  else
+    bad "D: quoter does not grant $t"
+  fi
+done
+
+STRAY=0
+while IFS= read -r card; do
+  [ "$card" = "$QUOTER" ] && continue
+  line="$(grep -m1 '^tools:' "$card" || true)"
+  if printf '%s' "$line" | grep -qE 'quote-render|quote-engine-run'; then
+    echo "  stray grant: $card" >&2
+    STRAY=$((STRAY + 1))
+  fi
+done < <(find "$ROOT/premium-plugins" "$ROOT/platform/templates/specialists/agents" -name '*.md' -type f 2>/dev/null)
+
+if [ "$STRAY" -eq 0 ]; then
+  ok "E: no other card grants a quote tool"
+else
+  bad "E: $STRAY other card(s) grant a quote tool"
+fi
+
+echo "──────── quote ownership contract summary ────────"
+echo "PASS=$PASS FAIL=$FAIL"
+[ "$FAIL" -eq 0 ]

package/payload/platform/scripts/lib/__tests__/account-settings-reconcile.test.sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+# reconcile_all_accounts_settings converges every account's hook set against the
+# shipped template and states the divergence count on every run.
+#
+# provision_account_dir writes the account's .claude/settings.json at provision
+# time only, and the upgrade path re-provisions the house account and no other.
+# An account created before a hook was added therefore runs a stale hook set
+# indefinitely, silently — which is how a client-quote gate came to be
+# registered on one of four accounts on a live install. Five one-hook backfill
+# libs were written that way, each after a different hook was found missing.
+# This lib converges the whole set instead.
+#
+# Covers:
+#   A. an account missing a template hook converges  → status=updated
+#   B. an already-matching account is left alone     → status=already-set
+#   C. an account with no settings file is seeded    → status=absent-seeded
+#   D. an unparseable file is reported, not rewritten → status=rewrite-failed
+#   E. the summary line is emitted on a re-run, stating its count
+#   F. the summary line counts the divergent accounts
+
+set -u
+
+LIB="$(cd "$(dirname "$0")/.." && pwd)/account-settings-reconcile.sh"
+if [ ! -f "$LIB" ]; then
+  echo "FAIL: $LIB missing" >&2
+  exit 1
+fi
+# shellcheck disable=SC1090
+. "$LIB"
+
+TMP=$(mktemp -d)
+trap 'rm -rf "$TMP"' EXIT
+
+TPL="$TMP/account-settings.json"
+printf '{"hooks":{"PreToolUse":[{"matcher":"Write","hooks":[{"type":"command","command":"bash a.sh"}]}]}}' > "$TPL"
+
+ACCTS="$TMP/accounts"
+mk() { mkdir -p "$ACCTS/$1/.claude"; printf '{}' > "$ACCTS/$1/account.json"; }
+
+PASS=0
+FAIL=0
+ok()  { echo "PASS: $1"; PASS=$((PASS + 1)); }
+bad() { echo "FAIL: $1" >&2; FAIL=$((FAIL + 1)); }
+
+mk stale;   printf '{"hooks":{"PreToolUse":[]}}' > "$ACCTS/stale/.claude/settings.json"
+mk current; cp "$TPL" "$ACCTS/current/.claude/settings.json"
+mk fresh
+mk broken;  printf 'not json' > "$ACCTS/broken/.claude/settings.json"
+
+OUT="$(MAXY_ACCOUNT_SETTINGS_TEMPLATE="$TPL" reconcile_all_accounts_settings "$ACCTS" 2>&1)"
+
+printf '%s' "$OUT" | grep -q 'account=stale status=updated' \
+  && ok "A: stale account converged" || bad "A: stale account not converged"
+printf '%s' "$OUT" | grep -q 'account=current status=already-set' \
+  && ok "B: matching account left alone" || bad "B: matching account not already-set"
+printf '%s' "$OUT" | grep -q 'account=fresh status=absent-seeded' \
+  && ok "C: missing settings seeded" || bad "C: missing settings not seeded"
+printf '%s' "$OUT" | grep -q 'account=broken status=rewrite-failed' \
+  && ok "D: unparseable file reported" || bad "D: unparseable file not reported"
+[ "$(cat "$ACCTS/broken/.claude/settings.json")" = "not json" ] \
+  && ok "D: unparseable file left untouched" || bad "D: unparseable file was rewritten"
+printf '%s' "$OUT" | grep -q 'accounts=4 divergent=3' \
+  && ok "F: summary counts the divergent accounts" || bad "F: wrong summary — $OUT"
+
+# The converged accounts stay converged; the unparseable one never does, which
+# is the standing signal.
+OUT2="$(MAXY_ACCOUNT_SETTINGS_TEMPLATE="$TPL" reconcile_all_accounts_settings "$ACCTS" 2>&1)"
+printf '%s' "$OUT2" | grep -q 'accounts=4 divergent=1' \
+  && ok "E: re-run states its count" || bad "E: wrong re-run summary — $OUT2"
+
+echo "──────── account-settings-reconcile summary ────────"
+echo "PASS=$PASS FAIL=$FAIL"
+[ "$FAIL" -eq 0 ]

package/payload/platform/scripts/lib/account-settings-reconcile.sh

@@ -0,0 +1,88 @@
+# account-settings-reconcile.sh — converge every account's Claude Code project
+# settings against the shipped template, and state the divergence count.
+#
+# provision_account_dir writes <accountDir>/.claude/settings.json from
+# platform/templates/account-settings.json at provision time only. The upgrade
+# path re-provisions the house account and no other, so an account created
+# before a hook was added runs a stale hook set indefinitely, and nothing says
+# so. A client-quote delivery gate was registered on one of four accounts on a
+# live install for exactly that reason, and the account it was missing from was
+# the one that quotes.
+#
+# Five one-hook backfill libs were written the same way, each after a different
+# hook was found missing on a live account: owned-dirs, askgate,
+# pdf-conformance, mailbox-inject, public-surface. This lib converges the whole
+# set instead, so a hook added to the template reaches every existing account on
+# the next install without a sixth bespoke backfill.
+#
+# Requires jq. Idempotent. Never echoes file contents. Fail-open: an unusable
+# file logs a status and is left untouched, never rewritten from a guess.
+#
+# Sourced by setup-account.sh; also runnable standalone for a manual repair.
+
+# ensure_account_settings <settings_file> <template_file>
+# Returns 0 when the file already matched the template, 1 when it diverged
+# (seeded, updated, unwritable, or unparseable). Logs exactly one
+#   [settings-reconcile] account=<id> status=<already-set|updated|absent-seeded|rewrite-failed|no-template>
+ensure_account_settings() {
+  local f="$1" tpl="$2"
+  local acct
+  acct="$(basename "$(dirname "$(dirname "$f")")")"
+
+  if [ ! -f "$tpl" ]; then
+    echo "[settings-reconcile] account=$acct status=no-template"
+    return 1
+  fi
+
+  if [ ! -f "$f" ]; then
+    mkdir -p "$(dirname "$f")" 2>/dev/null || true
+    if cp "$tpl" "$f" 2>/dev/null; then
+      echo "[settings-reconcile] account=$acct status=absent-seeded"
+    else
+      echo "[settings-reconcile] account=$acct status=rewrite-failed"
+    fi
+    return 1
+  fi
+
+  # Compare canonical forms, so key order and whitespace never read as drift.
+  # An empty result means jq refused the file; that is reported, not repaired —
+  # an unparseable settings file may carry an operator edit worth keeping, and
+  # this pass never destroys what it cannot read.
+  local before after
+  before="$(jq -S . "$f" 2>/dev/null || true)"
+  after="$(jq -S . "$tpl" 2>/dev/null || true)"
+  if [ -z "$before" ] || [ -z "$after" ]; then
+    echo "[settings-reconcile] account=$acct status=rewrite-failed"
+    return 1
+  fi
+  if [ "$before" = "$after" ]; then
+    echo "[settings-reconcile] account=$acct status=already-set"
+    return 0
+  fi
+
+  if cp "$tpl" "$f" 2>/dev/null; then
+    echo "[settings-reconcile] account=$acct status=updated"
+  else
+    echo "[settings-reconcile] account=$acct status=rewrite-failed"
+  fi
+  return 1
+}
+
+# reconcile_all_accounts_settings <accounts_dir>
+# Standing check + durable backfill across every account carrying an
+# account.json. Emits one status line per account plus one summary line on every
+# run, including a zero count — silence is not evidence of convergence.
+reconcile_all_accounts_settings() {
+  local accts="$1"
+  local tpl="${MAXY_ACCOUNT_SETTINGS_TEMPLATE:-${TEMPLATES_DIR:-}/account-settings.json}"
+  local n=0 divergent=0 acct
+  if [ -d "$accts" ]; then
+    for acct in "$accts"/*/; do
+      [ -f "$acct/account.json" ] || continue
+      n=$((n + 1))
+      ensure_account_settings "$acct/.claude/settings.json" "$tpl" || divergent=$((divergent + 1))
+    done
+  fi
+  echo "[settings-reconcile] accounts=$n divergent=$divergent"
+  return 0
+}