@rubytech/create-sitedesk-code 0.1.523 → 0.1.525

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

@@ -0,0 +1,80 @@
+#!/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.
+#
+# 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.
+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"
+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'
+
+if /usr/bin/grep -qF "$PROV_LINE" "$PROV"; then
+  ok "provision-account-dir.sh writes the hook into a UserPromptSubmit entry"
+else
+  bad "exact provision command line absent from $PROV"
+fi
+
+# The entry must sit inside the UserPromptSubmit array, not some other event.
+if 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)
+sys.exit(0 if m and "mailbox-inject.sh" in m.group(1) else 1)
+PY
+then
+  ok "the entry sits inside the UserPromptSubmit array, not another event"
+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"
+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"
+fi
+
+echo "----"
+echo "PASS=$PASS FAIL=$FAIL"
+if [ $((PASS+FAIL)) -ne 6 ]; then
+  echo "FAIL: expected 6 checks, ran $((PASS+FAIL))" >&2
+  exit 1
+fi
+[ "$FAIL" -eq 0 ]

package/payload/platform/scripts/__tests__/task-id-citation.test.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+# Standing guard for the citation scanner shared by the commit-time leak gate
+# and the bundle's payload audit. If those two stopped agreeing about what a
+# citation is, one surface would pass what the other rejects, and the payload
+# audit would be the one that fails a publish. The module is the reason they
+# cannot disagree, so it carries its own test.
+set -u
+MOD="$(cd "$(dirname "$0")/.." && pwd)/lib/task-id-citation.mjs"
+[[ -f "$MOD" ]] || { echo "FAIL: $MOD missing" >&2; exit 1; }
+PASS=0; FAIL=0
+
+# Runs findCitations over stdin and prints one `line:match` per hit.
+scan() {
+  node --input-type=module -e "
+    import { findCitations } from '${MOD}'
+    let s = ''
+    process.stdin.setEncoding('utf8')
+    for await (const c of process.stdin) s += c
+    for (const h of findCitations(s)) console.log(h.line + ':' + h.match)
+  "
+}
+
+check() {
+  local name="$1" expected="$2" actual="$3"
+  if [[ "$actual" == "$expected" ]]; then
+    echo "PASS: $name"; PASS=$((PASS+1))
+  else
+    echo "FAIL: $name - expected [$expected] got [$actual]" >&2; FAIL=$((FAIL+1))
+  fi
+}
+
+# 1. Clean prose -> no hits.
+out=$(printf 'A skill that does a thing.\n\nNothing internal here.\n' | scan)
+check "clean prose -> no citation" "" "$out"
+
+# 2. Parenthetical citation -> one hit on its own line.
+out=$(printf '# Skill\n\nDoes a thing (Task 999).\n' | scan)
+check "(Task 999) caught on line 3" "3:Task 999" "$out"
+
+# 3. Bare prose citation, capital T.
+out=$(printf 'Task 999 changed the routing.\n' | scan)
+check "bare Task 999 caught on line 1" "1:Task 999" "$out"
+
+# 4. Lowercase space-separated citation.
+out=$(printf 'Rewritten before task 127 landed.\n' | scan)
+check "lowercase task 127 caught" "1:task 127" "$out"
+
+# 5. Lowercase HYPHENATED stays exempt: that shape is a branch slug or a
+#    .tasks/ file path, both out of this scanner's scope.
+out=$(printf 'On branch task-537 the fix landed.\n' | scan)
+check "lowercase task-537 exempt" "" "$out"
+
+# 6. Single-digit counts stay exempt (the 2-digit floor).
+out=$(printf 'This is task 1 of 3.\n' | scan)
+check "task 1 of 3 exempt" "" "$out"
+
+# 7. Soft-wrapped citation split across two source lines. Renders as
+#    "(Task 659)" but matches neither line alone; the paragraph join is what
+#    catches it, and the reported line is where the match starts.
+out=$(printf 'A sentence that wraps before (Task\n659) closes it.\n' | scan)
+check "soft-wrapped Task 659 caught on line 1" "1:Task 659" "$out"
+
+# 8. Two citations in one paragraph -> both reported, each on its own line.
+out=$(printf 'First (Task 111) here.\nSecond (Task 222) there.\n' | scan)
+check "two citations in one paragraph" "$(printf '1:Task 111\n2:Task 222')" "$out"
+
+# 9. A blank line ends the paragraph, so the join never bridges one.
+out=$(printf 'Ends with the word Task\n\n999 opens the next paragraph.\n' | scan)
+check "join does not cross a blank line" "" "$out"
+
+echo "PASS=$PASS FAIL=$FAIL"
+[[ "$FAIL" -eq 0 ]]

package/payload/platform/scripts/check-canonical-tool-names.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // Strong build gate for canonical maxy MCP tool names (Task 502).
 //
-// Two checks, both must pass:
+// Three checks, all must pass:
 //   1. Regenerate-and-diff: the committed generated artifact
 //      (canonical-tool-names.generated.ts) must byte-match a fresh generation
 //      from platform/plugins/*/PLUGIN.md. A stale artifact fails the build —
@@ -14,10 +14,19 @@
 //      maxy name (mcp__<plugin>__<tool>) fails — it must be long. An unknown
 //      long-prefix maxy name fails — typo or stale. Non-maxy bridge namespaces
 //      (playwright, etc.) are ignored: their tool names are upstream-owned.
+//   3. Manifest field validation (Task 2126): every declared entry's riskClass
+//      must be one the session manager accepts, and every `tools:` entry's
+//      publicAllowlist and adminAllowlist must be YAML booleans. loadToolSurface
+//      throws on the first entry that is not, and that throw empties the tool
+//      surface for every plugin at once. Check 1 reads tool names and walks past
+//      the fields beside them, so before this check nothing an author ran could
+//      see the defect.
 
 import { readFileSync, readdirSync, statSync, existsSync } from 'node:fs'
 import { join } from 'node:path'
-import { computeCanonicalToolNames, MAXY_CODE_ROOT } from './lib/canonical-tool-names.mjs'
+import {
+  computeCanonicalToolNames, computeToolEntries, readRiskClasses, validateToolEntries, MAXY_CODE_ROOT,
+} from './lib/canonical-tool-names.mjs'
 import { renderArtifact, renderPluginsList } from './generate-canonical-tool-names.mjs'
 
 const GENERATED = join(
@@ -28,6 +37,11 @@ const PLUGINS_TXT = join(
   MAXY_CODE_ROOT, 'platform', 'plugins', 'admin', 'hooks', 'lib',
   'maxy-mcp-plugins.txt',
 )
+// The valid risk classes are read from here rather than restated, so this gate
+// cannot drift from the parser it protects.
+const TOOL_SURFACE_TS = join(
+  MAXY_CODE_ROOT, 'platform', 'services', 'claude-session-manager', 'src', 'tool-surface.ts',
+)
 
 const SCAN_DIRS = [
   join(MAXY_CODE_ROOT, 'platform', 'templates', 'specialists', 'agents'),
@@ -97,14 +111,32 @@ function main() {
     }
   }
 
-  const failed = driftError || violations.length > 0
+  // Check 3 — manifest field validation.
+  let riskClasses
+  try {
+    riskClasses = readRiskClasses(TOOL_SURFACE_TS)
+  } catch (err) {
+    console.error(`[gate] check-canonical-tool-names: ${err.message}`)
+    process.exit(1)
+  }
+  const entries = computeToolEntries()
+  const fieldViolations = validateToolEntries(entries, riskClasses)
+
+  const failed = driftError || violations.length > 0 || fieldViolations.length > 0
   if (driftError) console.error(driftError)
   if (violations.length > 0) {
     console.error('[gate] canonical-tool-names: instruction files name tools outside the live set:')
     for (const v of violations) console.error(`  ${v.file.replace(MAXY_CODE_ROOT + '/', '')}: ${v.name} — ${v.why}`)
   }
+  if (fieldViolations.length > 0) {
+    console.error('[gate] check-canonical-tool-names: PLUGIN.md tool entries declare fields the session manager rejects:')
+    for (const v of fieldViolations) console.error(`  ${v.plugin}/${v.name} — ${v.message}`)
+  }
   if (failed) process.exit(1)
-  console.log(`[gate] check-canonical-tool-names: PASS (${names.length} canonical names, scanned instruction files)`)
+  console.log(
+    `[gate] check-canonical-tool-names: PASS (${names.length} canonical names, ` +
+    `${entries.length} manifest entries validated, scanned instruction files)`,
+  )
 }
 
 main()

package/payload/platform/scripts/check-no-task-id-leaks.mjs

@@ -24,9 +24,10 @@
 // rule covers test titles, and test bodies that assert on citations are
 // equivalent to titles for this gate's purpose.
 
-import { readFileSync, readdirSync, statSync } from 'node:fs'
+import { readFileSync, readdirSync, statSync, existsSync } from 'node:fs'
 import { dirname, join, relative, sep, basename } from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { findCitations } from './lib/task-id-citation.mjs'
 
 const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url))
 // REPO_ROOT is overridable so the `.test.sh` self-test can point the gate at a
@@ -40,7 +41,6 @@ const SCAN_ROOTS = [
   join(REPO_ROOT, 'platform', 'plugins'),
   join(REPO_ROOT, 'platform', 'ui', 'server'),
   join(REPO_ROOT, 'platform', 'ui', 'app'),
-  join(REPO_ROOT, 'packages', 'create-maxy', 'src'),
 ]
 
 const ALLOWED_EXTS = new Set(['.sh', '.ts', '.tsx', '.js', '.mjs', '.cjs'])
@@ -52,27 +52,70 @@ const TASK_ID_RE = /\(Task \d+\)/
 // Markdown mode. Unlike code files — where a citation is legal in a comment and
 // only the parenthetical operator-visible form is rejected — a shipped `.md`
 // loads into a client-facing agent's context wholesale, so ANY citation form
-// leaks. Catches `Task NNN`, `(Task NNN)`, `Tasks NNN`, `since Task NNN`. It
-// deliberately does NOT match bare `#NNN`: every `#NNN` in the corpus is a hex
-// colour and there is no signal to separate `#732`-issue from `#732`-hex.
-// Two alternatives:
-//   `\bTasks?[\s-]+\d{2,4}` — capital-T, any separator: `Task 732`, `(Task 732)`,
-//     `Tasks 12`, the hyphenated `Pre-Task-748` / `post-Task-904` forms.
-//   `\btasks?\s+\d{2,4}` — lowercase but SPACE-separated only: catches prose
-//     citations like "before task 127", while a lowercase HYPHENATED `task-537`
-//     stays exempt because that shape is a branch slug or a `.tasks/<n>-…-task-NNN.md`
-//     file-path reference (file paths are out of this gate's scope). The 2-digit
-//     floor keeps single-digit domain counts ("task 1 of 3") out.
-const MD_TASK_ID_RE = /\bTasks?[\s-]+\d{2,4}|\btasks?\s+\d{2,4}/
+// leaks. The regex and the paragraph-aware scan live in
+// `lib/task-id-citation.mjs`, shared with the bundle's payload audit so the two
+// surfaces cannot disagree about what a citation is.
+//
+// The roots are what the client payload CARRIES, not a list somebody maintains.
+// `bundle.js` copies all of `platform/` and all of `premium-plugins/` into the
+// payload, so those two trees are the roots. Naming `platform/plugins` and
+// `platform/templates` instead is what let `platform/docs` ship 296 citations
+// to every install without this gate ever looking at it.
 const MD_SCAN_ROOTS = [
-  join(REPO_ROOT, 'platform', 'plugins'),
-  join(REPO_ROOT, 'platform', 'templates'),
-  // Premium bundles are copied verbatim into the client payload
-  // (`payload/premium-plugins/<bundle>/`), so their shipped markdown loads into
-  // the client agent the same as core plugins — any citation form leaks.
+  join(REPO_ROOT, 'platform'),
   join(REPO_ROOT, 'premium-plugins'),
 ]
 
+// The trees under the roots above that `bundle.js` keeps OUT of the payload,
+// mirroring its filter. A path here is unscanned because it does not ship; a
+// path not here is scanned because it does. Each entry names the exclusion in
+// `bundle.js` that makes it true, so the two files can be checked against each
+// other by reading them. `.docs/` and `.tasks/` need no entry: they sit outside
+// both roots and stay citation-rich.
+//
+// This list is a hand-kept mirror, and that is the one place the two surfaces
+// can still drift. An exclusion added to `bundle.js` and forgotten here makes
+// the gate scan a tree that does not ship, which is noisy but fail-safe. An
+// exclusion REMOVED from `bundle.js` and forgotten here is the dangerous
+// direction: a tree starts shipping and stops being scanned. The payload audit
+// in `bundle.js` is what catches that one, because it consults neither list.
+const MD_NOT_SHIPPED = [
+  // bundle.js `src.startsWith(UI_DIR)` — ui ships as a compiled bundle, not source.
+  join(REPO_ROOT, 'platform', 'ui'),
+  // bundle.js `src.startsWith(DOCS_DIR)` — sprint plans and specs are
+  // development records and do not ship.
+  join(REPO_ROOT, 'platform', 'docs'),
+  // bundle.js `src.startsWith(DOT_DOCS_DIR)` — same, for the dotted twin. The
+  // widened scan is what found this one: a `platform/*/` census does not match
+  // a dotdir, so `platform/.docs` shipped unseen by both the old roots and the
+  // measurement that motivated the change.
+  join(REPO_ROOT, 'platform', '.docs'),
+  // bundle.js `src.includes("/config/accounts/")`, `"/data/accounts/"` and
+  // `"/data/uploads/"` — live account data never ships. An account directory
+  // holds real markdown (`SCHEMA.md`, `AGENTS.md`), so without these three the
+  // gate would read a client's own files and could refuse a commit over a
+  // citation in something no payload carries.
+  join(REPO_ROOT, 'platform', 'config', 'accounts'),
+  join(REPO_ROOT, 'platform', 'data', 'accounts'),
+  join(REPO_ROOT, 'platform', 'data', 'uploads'),
+]
+
+function isNotShipped(file) {
+  return MD_NOT_SHIPPED.some((dir) => file === dir || file.startsWith(dir + sep))
+}
+
+// Every root names itself on every run. Before this, a tree outside the roots
+// produced no output at all, so nothing distinguished "scanned and clean" from
+// "never looked at", and a root that stopped existing was swallowed by walk()'s
+// bare catch — which is exactly how the archived `packages/create-maxy`
+// installer tree sat in this list for months pointing at a directory that does
+// not exist, proving nothing. A missing root logs rather than fails, because
+// the `.test.sh` fixture tree deliberately creates only some of them.
+function logRoot(kind, root, files) {
+  const exists = existsSync(root) ? 'yes' : 'no'
+  console.log(`[task-id-leak] root=${relative(REPO_ROOT, root)} kind=${kind} exists=${exists} files=${files}`)
+}
+
 function isCommentLine(line) {
   const trimmed = line.replace(/^\s+/, '')
   if (trimmed.startsWith('#')) return true
@@ -115,6 +158,7 @@ function* walk(root) {
 const leaks = []
 
 for (const root of SCAN_ROOTS) {
+  let scanned = 0
   for (const file of walk(root)) {
     if (!shouldScanFile(file)) continue
     let content
@@ -123,6 +167,7 @@ for (const root of SCAN_ROOTS) {
     } catch {
       continue
     }
+    scanned++
     const lines = content.split('\n')
     for (let i = 0; i < lines.length; i++) {
       const line = lines[i]
@@ -131,59 +176,30 @@ for (const root of SCAN_ROOTS) {
       leaks.push({ file: relative(REPO_ROOT, file), line: i + 1, content: line.trim() })
     }
   }
+  logRoot('code', root, scanned)
 }
 
-// Markdown scan — shipped operator-loadable docs. Reuses `walk` (which already
-// skips node_modules/dist/build/.next/payload/__tests__) and matches against
-// MD_TASK_ID_RE with no comment skip: the whole doc is agent content.
-// .docs/ and .tasks/ are not under MD_SCAN_ROOTS, so they stay citation-rich.
-//
-// Scanned per paragraph, not per line: a markdown soft-wrap can split a single
-// citation across two source lines (`... (Task\n659) ...`), which renders as
-// `(Task 659)` but matches neither line in isolation. Consecutive non-blank
-// lines are joined with a space (the soft-break a renderer would insert) and
-// scanned as one string; a blank line ends the paragraph, so the join never
-// crosses a paragraph break. Every match in the paragraph is reported, mapped
-// back to the source line where the match starts, preserving exact-line and
-// multi-citation reporting.
-const MD_TASK_ID_RE_G = new RegExp(MD_TASK_ID_RE.source, 'g')
-
-function flushParagraph(file, joined, lineStarts) {
-  if (joined === '') return
-  for (const m of joined.matchAll(MD_TASK_ID_RE_G)) {
-    let lineNo = lineStarts[0].lineNo
-    for (const ls of lineStarts) {
-      if (ls.offset <= m.index) lineNo = ls.lineNo
-    }
-    leaks.push({ file: relative(REPO_ROOT, file), line: lineNo, content: m[0] })
-  }
-}
-
+// Markdown scan — every `.md` the payload carries. Reuses `walk` (which already
+// skips node_modules/dist/build/.next/payload/__tests__), drops the trees
+// `bundle.js` excludes from the payload, and applies no comment skip: the whole
+// doc is agent content.
 for (const root of MD_SCAN_ROOTS) {
+  let scanned = 0
   for (const file of walk(root)) {
     if (!file.endsWith('.md')) continue
+    if (isNotShipped(file)) continue
     let content
     try {
       content = readFileSync(file, 'utf-8')
     } catch {
       continue
     }
-    const lines = content.split('\n')
-    let joined = ''
-    let lineStarts = []
-    for (let i = 0; i < lines.length; i++) {
-      if (lines[i].trim() === '') {
-        flushParagraph(file, joined, lineStarts)
-        joined = ''
-        lineStarts = []
-        continue
-      }
-      if (joined !== '') joined += ' '
-      lineStarts.push({ offset: joined.length, lineNo: i + 1 })
-      joined += lines[i]
+    scanned++
+    for (const c of findCitations(content)) {
+      leaks.push({ file: relative(REPO_ROOT, file), line: c.line, content: c.match })
     }
-    flushParagraph(file, joined, lineStarts)
   }
+  logRoot('md', root, scanned)
 }
 
 if (leaks.length > 0) {
@@ -194,8 +210,10 @@ if (leaks.length > 0) {
   console.error('')
   console.error('Code files: citations belong in inline comments only, never in operator-visible')
   console.error('strings (stderr/stdout, logs, systemd --description=, error messages, console.*).')
-  console.error('Shipped markdown (platform/plugins, platform/templates, premium-plugins): no task')
-  console.error('citation in any form — the whole doc loads into a client-facing agent. Dev docs')
-  console.error('(.docs/, .tasks/) are exempt and keep their citations.')
+  console.error('Shipped markdown (everything under platform/ and premium-plugins/ that the payload')
+  console.error('carries): no task citation in any form — the whole doc loads into a client-facing')
+  console.error('agent. The trees that do NOT ship are exempt, and MD_NOT_SHIPPED in this file is')
+  console.error('the list of them; the dev docs (.docs/, .tasks/) sit outside the roots entirely')
+  console.error('and keep their citations.')
   process.exit(1)
 }

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

@@ -0,0 +1,166 @@
+#!/usr/bin/env bash
+# Regression test for account-settings-mailbox-inject.sh (Task 2157).
+#
+# The lib retrofits the per-turn <mailboxes> injection hook onto existing
+# accounts' .claude/settings.json on every install. provision-account-dir.sh
+# writes the UserPromptSubmit array at provision time only, and setup-account.sh
+# re-provisions the HOUSE account only, so a client sub-account created by the
+# admin-core account-lifecycle tool never gets the hook without this reconcile.
+#
+# Covers:
+#   1. Array with a sibling hook   -> updated, command appended, sibling preserved
+#   2. Re-run on the same file     -> already-set, file byte-identical
+#   3. Empty UserPromptSubmit array-> updated, whole entry created
+#   4. Command already present     -> already-set, no duplicate
+#   5. No .hooks.UserPromptSubmit  -> no-hooks, file untouched
+#   6. File absent                 -> absent
+#   7. Malformed JSON              -> rewrite-failed, file untouched
+#   8. settings.json is an array   -> rewrite-failed or no-hooks, file untouched
+#   9. reconcile_all_accounts_*    -> patches every account.json dir, skips others
+#  10. No temp file is ever left behind, on any path
+#
+# All cases assert the [backfill-2157] status token and the post-state of the file.
+
+set -u
+
+LIB="$(cd "$(dirname "$0")/.." && pwd)/account-settings-mailbox-inject.sh"
+if [ ! -f "$LIB" ]; then
+  echo "FAIL: $LIB not found" >&2
+  exit 1
+fi
+# shellcheck source=/dev/null
+. "$LIB"
+
+CMD='bash $PLATFORM_ROOT/plugins/admin/hooks/mailbox-inject.sh'
+SIB='bash $PLATFORM_ROOT/plugins/admin/hooks/datetime-inject.sh'
+
+PASS=0
+FAIL=0
+TMP="$(mktemp -d)"
+trap 'rm -rf "$TMP"' EXIT
+
+ok()  { echo "PASS: $1"; PASS=$((PASS+1)); }
+bad() { echo "FAIL: $1" >&2; FAIL=$((FAIL+1)); }
+
+# cmds <file> -> every command string in the UserPromptSubmit array, one per line
+cmds() { jq -r '[.hooks.UserPromptSubmit[]?.hooks[]?.command] | .[]' "$1" 2>/dev/null; }
+status_of() { printf '%s' "$1" | /usr/bin/sed 's/.*status=//'; }
+
+# --- 1. array with a sibling hook -> updated, sibling preserved -------------
+F="$TMP/a.json"
+printf '%s' "{\"hooks\":{\"UserPromptSubmit\":[{\"hooks\":[{\"type\":\"command\",\"command\":\"$SIB\"}]}]}}" > "$F"
+OUT=$(ensure_mailbox_inject_hook "$F")
+if [ "$(status_of "$OUT")" = "updated" ] \
+   && [ "$(cmds "$F" | /usr/bin/grep -cF "$CMD")" -eq 1 ] \
+   && [ "$(cmds "$F" | /usr/bin/grep -cF "$SIB")" -eq 1 ]; then
+  ok "existing array -> updated, sibling hook preserved"
+else
+  bad "case 1 (out=$OUT cmds=$(cmds "$F" | tr '\n' ' '))"
+fi
+
+# --- 2. re-run -> already-set, byte-identical -------------------------------
+B=$(shasum "$F" | /usr/bin/cut -d' ' -f1)
+OUT=$(ensure_mailbox_inject_hook "$F")
+A=$(shasum "$F" | /usr/bin/cut -d' ' -f1)
+if [ "$(status_of "$OUT")" = "already-set" ] && [ "$B" = "$A" ] \
+   && [ "$(cmds "$F" | /usr/bin/grep -cF "$CMD")" -eq 1 ]; then
+  ok "re-run -> already-set, file byte-identical, no duplicate"
+else
+  bad "case 2 (out=$OUT before=$B after=$A)"
+fi
+
+# --- 3. empty array -> updated, whole entry created -------------------------
+F="$TMP/b.json"; printf '%s' '{"hooks":{"UserPromptSubmit":[]}}' > "$F"
+OUT=$(ensure_mailbox_inject_hook "$F")
+if [ "$(status_of "$OUT")" = "updated" ] && [ "$(cmds "$F" | /usr/bin/grep -cF "$CMD")" -eq 1 ]; then
+  ok "empty array -> updated, entry created"
+else
+  bad "case 3 (out=$OUT cmds=$(cmds "$F" | tr '\n' ' '))"
+fi
+
+# --- 4. command already present in a later entry -> already-set, no dupe ----
+F="$TMP/c.json"
+printf '%s' "{\"hooks\":{\"UserPromptSubmit\":[{\"hooks\":[{\"type\":\"command\",\"command\":\"$SIB\"}]},{\"hooks\":[{\"type\":\"command\",\"command\":\"$CMD\"}]}]}}" > "$F"
+OUT=$(ensure_mailbox_inject_hook "$F")
+if [ "$(status_of "$OUT")" = "already-set" ] && [ "$(cmds "$F" | /usr/bin/grep -cF "$CMD")" -eq 1 ]; then
+  ok "command present in a later entry -> already-set, not duplicated"
+else
+  bad "case 4 (out=$OUT cmds=$(cmds "$F" | tr '\n' ' '))"
+fi
+
+# --- 5. no UserPromptSubmit -> no-hooks, untouched --------------------------
+F="$TMP/d.json"; printf '%s' '{"permissions":{}}' > "$F"
+B=$(shasum "$F" | /usr/bin/cut -d' ' -f1); OUT=$(ensure_mailbox_inject_hook "$F"); A=$(shasum "$F" | /usr/bin/cut -d' ' -f1)
+if [ "$(status_of "$OUT")" = "no-hooks" ] && [ "$B" = "$A" ]; then
+  ok "no UserPromptSubmit array -> no-hooks, file untouched"
+else
+  bad "case 5 (out=$OUT)"
+fi
+
+# --- 6. file absent -> absent ----------------------------------------------
+OUT=$(ensure_mailbox_inject_hook "$TMP/does-not-exist.json")
+if [ "$(status_of "$OUT")" = "absent" ]; then
+  ok "file absent -> absent"
+else
+  bad "case 6 (out=$OUT)"
+fi
+
+# --- 7. malformed JSON -> rewrite-failed, untouched -------------------------
+F="$TMP/e.json"; printf 'not json at all' > "$F"
+B=$(shasum "$F" | /usr/bin/cut -d' ' -f1); OUT=$(ensure_mailbox_inject_hook "$F"); A=$(shasum "$F" | /usr/bin/cut -d' ' -f1)
+if [ "$(status_of "$OUT")" = "rewrite-failed" ] && [ "$B" = "$A" ]; then
+  ok "malformed JSON -> rewrite-failed, file untouched"
+else
+  bad "case 7 (out=$OUT)"
+fi
+
+# --- 8. settings.json is a JSON array -> not patched, untouched -------------
+F="$TMP/f.json"; printf '%s' '[]' > "$F"
+B=$(shasum "$F" | /usr/bin/cut -d' ' -f1); OUT=$(ensure_mailbox_inject_hook "$F"); A=$(shasum "$F" | /usr/bin/cut -d' ' -f1)
+S=$(status_of "$OUT")
+if { [ "$S" = "no-hooks" ] || [ "$S" = "rewrite-failed" ]; } && [ "$B" = "$A" ]; then
+  ok "settings.json that is an array -> not patched, file untouched"
+else
+  bad "case 8 (out=$OUT before=$B after=$A)"
+fi
+
+# --- 9. reconcile walks account dirs only ----------------------------------
+R="$TMP/accts"; mkdir -p "$R/one/.claude" "$R/two/.claude" "$R/notanaccount/.claude"
+printf '%s' '{}' > "$R/one/account.json"; printf '%s' '{}' > "$R/two/account.json"
+for d in one two notanaccount; do
+  printf '%s' "{\"hooks\":{\"UserPromptSubmit\":[{\"hooks\":[{\"type\":\"command\",\"command\":\"$SIB\"}]}]}}" > "$R/$d/.claude/settings.json"
+done
+OUT=$(reconcile_all_accounts_mailbox_inject "$R")
+if [ "$(printf '%s' "$OUT" | /usr/bin/grep -c 'status=updated')" -eq 2 ] \
+   && [ "$(cmds "$R/one/.claude/settings.json" | /usr/bin/grep -cF "$CMD")" -eq 1 ] \
+   && [ "$(cmds "$R/two/.claude/settings.json" | /usr/bin/grep -cF "$CMD")" -eq 1 ] \
+   && [ "$(cmds "$R/notanaccount/.claude/settings.json" | /usr/bin/grep -cF "$CMD")" -eq 0 ]; then
+  ok "reconcile patches account.json dirs only"
+else
+  bad "case 9 (out=$OUT)"
+fi
+
+# --- 10. no temp file left behind on any path ------------------------------
+if [ "$(find "$TMP" -name '*.2157.tmp' | /usr/bin/wc -l | tr -d ' ')" -eq 0 ]; then
+  ok "no .2157.tmp file left behind on any path"
+else
+  bad "case 10 (strays: $(find "$TMP" -name '*.2157.tmp'))"
+fi
+
+# --- 11. never returns non-zero, even on the failure paths -----------------
+ensure_mailbox_inject_hook "$TMP/e.json" >/dev/null; r1=$?
+ensure_mailbox_inject_hook "$TMP/nope.json" >/dev/null; r2=$?
+reconcile_all_accounts_mailbox_inject "$TMP/no-such-dir" >/dev/null; r3=$?
+if [ "$r1" -eq 0 ] && [ "$r2" -eq 0 ] && [ "$r3" -eq 0 ]; then
+  ok "every path returns 0, so a caller running set -e is never aborted"
+else
+  bad "case 11 (malformed=$r1 absent=$r2 nodir=$r3)"
+fi
+
+echo "----"
+echo "PASS=$PASS FAIL=$FAIL"
+if [ $((PASS+FAIL)) -ne 11 ]; then
+  echo "FAIL: expected 11 cases, ran $((PASS+FAIL))" >&2
+  exit 1
+fi
+[ "$FAIL" -eq 0 ]