@rubytech/create-sitedesk-code 0.1.508 → 0.1.510

package/payload/platform/scripts/__tests__/check-brand-cache.test.sh

@@ -0,0 +1,231 @@
+#!/usr/bin/env bash
+# Tests for check-brand-cache.sh (Task 2019). Fixture-driven: builds a throwaway
+# install dir + config dir per case and stubs the fetch command, because the real
+# one crosses a Cloudflare edge that no test can hold still. sha256 and the
+# ingress parse are the real code paths — those are what this asserts.
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CHECK="$SCRIPT_DIR/../check-brand-cache.sh"
+
+PASS=0
+FAIL=0
+
+run_case() {
+  local name="$1"; shift
+  echo ""
+  echo "=== CASE: $name ==="
+  if "$@"; then
+    PASS=$((PASS + 1)); echo "PASS: $name"
+  else
+    FAIL=$((FAIL + 1)); echo "FAIL: $name"
+  fi
+}
+
+# Build install dir with two brand files and brand-defaults.css. Echoes its path.
+mk_install() {
+  local d
+  d="$(mktemp -d "${TMPDIR:-/tmp}/brand-cache-install.XXXXXX")"
+  mkdir -p "$d/server/public/brand"
+  printf 'lime-logo-bytes' > "$d/server/public/brand/logo.png"
+  printf 'lime-icon-bytes' > "$d/server/public/brand/icon.png"
+  printf ':root{--brand:#c3f53c}' > "$d/server/public/brand-defaults.css"
+  echo "$d"
+}
+
+# Build a config dir whose cloudflared/config.yml has the given ingress hosts.
+mk_config_with_hosts() {
+  local d; d="$(mktemp -d "${TMPDIR:-/tmp}/brand-cache-config.XXXXXX")"
+  mkdir -p "$d/cloudflared"
+  { echo "ingress:"; for h in "$@"; do echo "  - hostname: $h"; done; echo "  - service: http_status:404"; } \
+    > "$d/cloudflared/config.yml"
+  echo "$d"
+}
+
+mk_config_no_tunnel() {
+  local d; d="$(mktemp -d "${TMPDIR:-/tmp}/brand-cache-config.XXXXXX")"
+  echo "$d"
+}
+
+# A config dir with no cloudflared ingress but an alias-domains.json, the
+# second source resolvePublicHostname reads.
+mk_config_alias_only() {
+  local d; d="$(mktemp -d "${TMPDIR:-/tmp}/brand-cache-config.XXXXXX")"
+  printf '["public.realagent.app"]' > "$d/alias-domains.json"
+  echo "$d"
+}
+
+# Stub curl. $1 = dir whose files it serves as the "edge", keyed by basename.
+# Writes headers to the -D path and the body to the -o path, exit 0.
+mk_curl_stub() {
+  local serve_dir="$1" stub
+  stub="$(mktemp "${TMPDIR:-/tmp}/brand-cache-curl.XXXXXX")"
+  cat > "$stub" <<STUB
+#!/usr/bin/env bash
+hdr=""; out=""; url=""
+while [ \$# -gt 0 ]; do
+  case "\$1" in
+    -D) hdr="\$2"; shift 2 ;;
+    -o) out="\$2"; shift 2 ;;
+    -*) shift ;;
+    *) url="\$1"; shift ;;
+  esac
+done
+name="\${url##*/}"
+printf 'HTTP/2 200\r\ncf-cache-status: HIT\r\nage: 5352\r\n\r\n' > "\$hdr"
+cat "$serve_dir/\$name" > "\$out"
+STUB
+  chmod +x "$stub"
+  echo "$stub"
+}
+
+case_clean_install_reports_clean() {
+  local i c stub edge out rc
+  i="$(mk_install)"; c="$(mk_config_with_hosts operations.realagent.network)"
+  # Edge serves exactly what is on disk.
+  edge="$(mktemp -d "${TMPDIR:-/tmp}/brand-cache-edge.XXXXXX")"
+  cp "$i/server/public/brand/"* "$edge/"
+  cp "$i/server/public/brand-defaults.css" "$edge/"
+  stub="$(mk_curl_stub "$edge")"
+  out="$(BRAND_CACHE_CURL="$stub" "$CHECK" --install-dir "$i" --config-dir "$c" 2>/dev/null)"
+  rc=$?
+  [ "$rc" -eq 0 ] || { echo "  expected exit 0, got $rc"; rm -rf "$i" "$c" "$edge" "$stub"; return 1; }
+  # files=2 pinned as an integer: a \d+ match also accepts files=0, and a
+  # hostname resolving to nothing would then read as a pass.
+  echo "$out" | grep -qx "\[brand-cache\] clean host=operations.realagent.network files=2" \
+    || { echo "  no clean line with files=2; got: $out"; rm -rf "$i" "$c" "$edge" "$stub"; return 1; }
+  rm -rf "$i" "$c" "$edge" "$stub"; return 0
+}
+
+case_stale_edge_reports_stale_on_stderr() {
+  local i c stub edge err rc
+  i="$(mk_install)"; c="$(mk_config_with_hosts operations.realagent.network)"
+  edge="$(mktemp -d "${TMPDIR:-/tmp}/brand-cache-edge.XXXXXX")"
+  cp "$i/server/public/brand/"* "$edge/"
+  cp "$i/server/public/brand-defaults.css" "$edge/"
+  # The measured symptom: the edge holds the retired mark, disk holds the new one.
+  printf 'black-square-bytes' > "$edge/logo.png"
+  stub="$(mk_curl_stub "$edge")"
+  err="$(BRAND_CACHE_CURL="$stub" "$CHECK" --install-dir "$i" --config-dir "$c" 2>&1 >/dev/null)"
+  rc=$?
+  [ "$rc" -eq 1 ] || { echo "  expected exit 1, got $rc"; rm -rf "$i" "$c" "$edge" "$stub"; return 1; }
+  echo "$err" | grep -qE "^\[brand-cache\] STALE host=operations\.realagent\.network path=/brand/logo\.png edge=[0-9a-f]{7} disk=[0-9a-f]{7} cf-cache-status=HIT age=5352$" \
+    || { echo "  no STALE line for /brand/logo.png; got: $err"; rm -rf "$i" "$c" "$edge" "$stub"; return 1; }
+  rm -rf "$i" "$c" "$edge" "$stub"; return 0
+}
+
+case_no_tunnel_reports_skipped() {
+  local i c out rc
+  i="$(mk_install)"; c="$(mk_config_no_tunnel)"
+  out="$("$CHECK" --install-dir "$i" --config-dir "$c" 2>/dev/null)"
+  rc=$?
+  [ "$rc" -eq 0 ] || { echo "  expected exit 0, got $rc"; rm -rf "$i" "$c"; return 1; }
+  echo "$out" | grep -qx "\[brand-cache\] skipped host=none reason=no-tunnel-ingress" \
+    || { echo "  no skipped line; got: $out"; rm -rf "$i" "$c"; return 1; }
+  rm -rf "$i" "$c"; return 0
+}
+
+case_localhost_only_ingress_is_no_tunnel() {
+  local i c out rc
+  i="$(mk_install)"; c="$(mk_config_with_hosts localhost muvin.local)"
+  out="$("$CHECK" --install-dir "$i" --config-dir "$c" 2>/dev/null)"
+  rc=$?
+  [ "$rc" -eq 0 ] || { echo "  expected exit 0, got $rc"; rm -rf "$i" "$c"; return 1; }
+  echo "$out" | grep -qx "\[brand-cache\] skipped host=none reason=no-tunnel-ingress" \
+    || { echo "  localhost/.local counted as ingress; got: $out"; rm -rf "$i" "$c"; return 1; }
+  rm -rf "$i" "$c"; return 0
+}
+
+case_unfetchable_asset_is_not_silently_clean() {
+  local i c stub err rc
+  i="$(mk_install)"; c="$(mk_config_with_hosts operations.realagent.network)"
+  # Stub that answers 502 with an empty body for every path.
+  stub="$(mktemp "${TMPDIR:-/tmp}/brand-cache-curl.XXXXXX")"
+  cat > "$stub" <<'STUB'
+#!/usr/bin/env bash
+hdr=""; out=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -D) hdr="$2"; shift 2 ;;
+    -o) out="$2"; shift 2 ;;
+    -*) shift ;;
+    *) shift ;;
+  esac
+done
+printf 'HTTP/2 502\r\n\r\n' > "$hdr"
+: > "$out"
+STUB
+  chmod +x "$stub"
+  err="$(BRAND_CACHE_CURL="$stub" "$CHECK" --install-dir "$i" --config-dir "$c" 2>&1 >/dev/null)"
+  rc=$?
+  [ "$rc" -eq 1 ] || { echo "  expected exit 1, got $rc"; rm -rf "$i" "$c" "$stub"; return 1; }
+  echo "$err" | grep -qE "^\[brand-cache\] UNREACHABLE host=operations\.realagent\.network path=/brand/logo\.png http=502$" \
+    || { echo "  no UNREACHABLE line; got: $err"; rm -rf "$i" "$c" "$stub"; return 1; }
+  rm -rf "$i" "$c" "$stub"; return 0
+}
+
+case_no_assets_is_a_named_skip_not_a_clean() {
+  local i c out rc
+  i="$(mktemp -d "${TMPDIR:-/tmp}/brand-cache-install.XXXXXX")"; mkdir -p "$i/server/public"
+  c="$(mk_config_with_hosts operations.realagent.network)"
+  # bash 3.2 (macOS) errors on "${PATHS[@]}" for an empty array under `set -u`,
+  # so this also pins that the loop is never entered with nothing to compare.
+  out="$(/bin/bash "$CHECK" --install-dir "$i" --config-dir "$c" 2>&1)"
+  rc=$?
+  [ "$rc" -eq 0 ] || { echo "  expected exit 0, got $rc; got: $out"; rm -rf "$i" "$c"; return 1; }
+  echo "$out" | grep -qx "\[brand-cache\] skipped host=operations.realagent.network reason=no-brand-assets" \
+    || { echo "  no named skip for an empty asset list; got: $out"; rm -rf "$i" "$c"; return 1; }
+  # files=0 must never be emitted: the task's own pinning exists so an empty
+  # comparison cannot read as a pass.
+  echo "$out" | grep -q "files=0" \
+    && { echo "  emitted files=0, which reads as a pass"; rm -rf "$i" "$c"; return 1; }
+  rm -rf "$i" "$c"; return 0
+}
+
+case_alias_only_install_is_checked_not_skipped() {
+  local i c stub edge out rc
+  i="$(mk_install)"; c="$(mk_config_alias_only)"
+  edge="$(mktemp -d "${TMPDIR:-/tmp}/brand-cache-edge.XXXXXX")"
+  cp "$i/server/public/brand/"* "$edge/"
+  stub="$(mk_curl_stub "$edge")"
+  out="$(BRAND_CACHE_CURL="$stub" "$CHECK" --install-dir "$i" --config-dir "$c" 2>/dev/null)"
+  rc=$?
+  [ "$rc" -eq 0 ] || { echo "  expected exit 0, got $rc"; rm -rf "$i" "$c" "$edge" "$stub"; return 1; }
+  # An install with an alias edge and no ingress row does have an edge that can
+  # diverge, so reporting `skipped` there would read as nothing-to-check on the
+  # one state the skip wording promises it is not.
+  echo "$out" | grep -qx "\[brand-cache\] clean host=public.realagent.app files=2" \
+    || { echo "  alias-only install was not checked; got: $out"; rm -rf "$i" "$c" "$edge" "$stub"; return 1; }
+  rm -rf "$i" "$c" "$edge" "$stub"; return 0
+}
+
+case_brand_defaults_css_is_not_fetched() {
+  local i c stub edge out rc
+  i="$(mk_install)"; c="$(mk_config_with_hosts admin.realagent.network public.realagent.network)"
+  edge="$(mktemp -d "${TMPDIR:-/tmp}/brand-cache-edge.XXXXXX")"
+  cp "$i/server/public/brand/"* "$edge/"
+  # No brand-defaults.css at the edge. The gate at server/index.ts:1311-1322
+  # exempts /brand/ but not /brand-defaults.css, so through an admin-gated host
+  # that path answers with a login page at status 200 — hashing that against
+  # the stylesheet would be a permanent false STALE with no cache involved.
+  stub="$(mk_curl_stub "$edge")"
+  out="$(BRAND_CACHE_CURL="$stub" "$CHECK" --install-dir "$i" --config-dir "$c" 2>/dev/null)"
+  rc=$?
+  [ "$rc" -eq 0 ] || { echo "  expected exit 0, got $rc"; rm -rf "$i" "$c" "$edge" "$stub"; return 1; }
+  echo "$out" | grep -qx "\[brand-cache\] clean host=admin.realagent.network files=2" \
+    || { echo "  expected only the two /brand/ files; got: $out"; rm -rf "$i" "$c" "$edge" "$stub"; return 1; }
+  rm -rf "$i" "$c" "$edge" "$stub"; return 0
+}
+
+run_case "clean install reports clean with a pinned file count" case_clean_install_reports_clean
+run_case "stale edge reports STALE on stderr and exits 1" case_stale_edge_reports_stale_on_stderr
+run_case "no tunnel ingress reports skipped and exits 0" case_no_tunnel_reports_skipped
+run_case "localhost/.local-only ingress counts as no tunnel" case_localhost_only_ingress_is_no_tunnel
+run_case "an unfetchable asset is reported, never counted clean" case_unfetchable_asset_is_not_silently_clean
+run_case "an empty asset list is a named skip, never files=0" case_no_assets_is_a_named_skip_not_a_clean
+run_case "an alias-only install is checked, not skipped" case_alias_only_install_is_checked_not_skipped
+run_case "brand-defaults.css is not fetched through a gated host" case_brand_defaults_css_is_not_fetched
+
+echo ""
+echo "PASS=$PASS FAIL=$FAIL"
+[ "$FAIL" -eq 0 ]

package/payload/platform/scripts/check-brand-cache.sh

@@ -0,0 +1,138 @@
+#!/usr/bin/env bash
+# check-brand-cache.sh — reconcile the bytes the public hostname returns
+# against the bytes on disk (Task 2019).
+#
+# The failure this exists for emits no event at either end. The installer
+# writes the new brand bytes and logs a successful upgrade; the origin serves
+# them correctly to anyone asking it directly; Cloudflare's edge serves the
+# pre-upgrade ones and reports `HIT` to nobody looking. There is no action to
+# log and re-running the upgrade does not surface it, so only a reconciliation
+# of served bytes against on-disk bytes reveals the state. That is the
+# condition behind the 2026-07-26 report, where the regenerated Real Agent logo
+# was correct on disk and invisible through the hostname for four hours.
+#
+#   $ check-brand-cache.sh --install-dir <dir> --config-dir <dir>
+#
+# stdout, exit 0:  [brand-cache] clean host=<h> files=<n>
+# stdout, exit 0:  [brand-cache] skipped host=none reason=no-tunnel-ingress
+# stderr, exit 1:  [brand-cache] STALE host=<h> path=<p> edge=<sha7> disk=<sha7> cf-cache-status=<s> age=<n>
+# stderr, exit 1:  [brand-cache] UNREACHABLE host=<h> path=<p> http=<code>
+#
+# No ingress hostname and no alias domain means no edge and therefore no
+# possible divergence, so that is a skip, not a pass — a caller must never read
+# the two as the same.
+#
+# Scope: the files under server/public/brand/ only. See the PATHS block below.
+#
+# BRAND_CACHE_CURL overrides the fetch command (tests stub it).
+set -uo pipefail
+
+INSTALL_DIR=""
+CONFIG_DIR=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --install-dir) INSTALL_DIR="$2"; shift 2 ;;
+    --config-dir) CONFIG_DIR="$2"; shift 2 ;;
+    *) echo "[brand-cache] unknown argument: $1" >&2; exit 2 ;;
+  esac
+done
+if [ -z "$INSTALL_DIR" ] || [ -z "$CONFIG_DIR" ]; then
+  echo "[brand-cache] usage: check-brand-cache.sh --install-dir <dir> --config-dir <dir>" >&2
+  exit 2
+fi
+
+CURL="${BRAND_CACHE_CURL:-curl}"
+
+# sha256sum is GNU; darwin ships shasum. Both print "<digest>  <path>".
+sha256() {
+  if command -v sha256sum >/dev/null 2>&1; then sha256sum "$1" | awk '{print $1}'
+  else shasum -a 256 "$1" | awk '{print $1}'; fi
+}
+
+# The hostname to probe, read from the same two sources and with the same
+# exclusions as platform/plugins/admin/mcp/src/lib/public-hostname.ts:
+# cloudflared/config.yml first, then alias-domains.json. First non-excluded
+# wins within each source.
+#
+# No apex tiebreak, and no attempt to pick the *public* host over the admin
+# one: only /brand/ assets are fetched, and the admin gate exempts /brand/ on
+# every host class (server/index.ts:1311-1322), so any ingress host serves them
+# identically. The alias source is read because an install whose edge is an
+# alias domain with no ingress row does have an edge that can diverge, and
+# reporting `skipped` there would read as nothing-to-check.
+resolve_host() {
+  local cfg="$CONFIG_DIR/cloudflared/config.yml" alias="$CONFIG_DIR/alias-domains.json" h
+  if [ -f "$cfg" ]; then
+    h="$(sed -n 's/^[[:space:]]*-[[:space:]]*hostname:[[:space:]]*\([^[:space:]]*\).*/\1/p' "$cfg" \
+      | grep -v '^localhost$' | grep -v '\.local$' | head -1)"
+    if [ -n "$h" ]; then echo "$h"; return 0; fi
+  fi
+  [ -f "$alias" ] || return 0
+  tr ',' '\n' < "$alias" | sed -n 's/.*"\([^"]*\)".*/\1/p' \
+    | grep -v '^localhost$' | grep -v '\.local$' | head -1
+}
+
+HOST="$(resolve_host)"
+if [ -z "$HOST" ]; then
+  echo "[brand-cache] skipped host=none reason=no-tunnel-ingress"
+  exit 0
+fi
+
+# /brand/ only. /brand-defaults.css is NOT exempt from the admin gate
+# (server/index.ts:1311-1322 lists /favicon.ico, /assets/, /brand/,
+# /api/calendar/free-busy and the PWA paths, and nothing else), so through an
+# admin-gated or operator host it answers with a login page at status 200
+# (index.ts:1379). Hashing that against the stylesheet on disk would be a
+# permanent STALE with no cache involved, which would both bury a real
+# divergence and make the clean line unreachable. Covering it, and the page
+# shells, needs a resolved public hostname — Task 2026.
+PUBLIC_DIR="$INSTALL_DIR/server/public"
+PATHS=()
+if [ -d "$PUBLIC_DIR/brand" ]; then
+  while IFS= read -r f; do PATHS+=("/brand/$(basename "$f")"); done \
+    < <(find "$PUBLIC_DIR/brand" -maxdepth 1 -type f | sort)
+fi
+
+# Nothing to compare is a skip with its own reason, not a clean run. Emitting
+# `files=0` here would read as a pass on an install whose payload never
+# deployed, and that is the dead signal the file count is pinned against.
+# Also the guard for bash 3.2 (darwin), where "${PATHS[@]}" on an empty array
+# is an unbound-variable error under `set -u`.
+if [ "${#PATHS[@]}" -eq 0 ]; then
+  echo "[brand-cache] skipped host=$HOST reason=no-brand-assets"
+  exit 0
+fi
+
+TMP="$(mktemp -d "${TMPDIR:-/tmp}/brand-cache.XXXXXX")"
+trap 'rm -rf "$TMP"' EXIT
+
+FAILED=0
+CHECKED=0
+for p in "${PATHS[@]}"; do
+  body="$TMP/body"; hdr="$TMP/hdr"
+  "$CURL" -sS -L -D "$hdr" -o "$body" "https://$HOST$p" >/dev/null 2>&1
+  code="$(awk 'tolower($0) ~ /^http\// {c=$2} END{print c+0}' "$hdr" 2>/dev/null)"
+  if [ "$code" != "200" ]; then
+    echo "[brand-cache] UNREACHABLE host=$HOST path=$p http=$code" >&2
+    FAILED=1
+    continue
+  fi
+  edge="$(sha256 "$body")"
+  disk="$(sha256 "$PUBLIC_DIR$p")"
+  if [ "$edge" != "$disk" ]; then
+    # tail -1, not head -1: -L means $hdr can hold several header blocks, and
+    # the cache state that matters is the one on the response the bytes came
+    # from. head -1 would name a redirect hop's cache state instead, which is
+    # the field an operator reads to tell this fault from an origin fault.
+    status="$(awk 'tolower($1) == "cf-cache-status:" {print $2}' "$hdr" | tr -d '\r' | tail -1)"
+    age="$(awk 'tolower($1) == "age:" {print $2}' "$hdr" | tr -d '\r' | tail -1)"
+    echo "[brand-cache] STALE host=$HOST path=$p edge=${edge:0:7} disk=${disk:0:7} cf-cache-status=${status:-none} age=${age:-0}" >&2
+    FAILED=1
+    continue
+  fi
+  CHECKED=$((CHECKED + 1))
+done
+
+[ "$FAILED" -eq 1 ] && exit 1
+echo "[brand-cache] clean host=$HOST files=$CHECKED"
+exit 0

package/payload/platform/scripts/lib/account-schema-owned-dirs.py

@@ -1,16 +1,23 @@
 #!/usr/bin/env python3
-"""Resolve plugin-declared account-owned top-level dirs for the brand and merge
-them into an account's SCHEMA.md.
+"""Resolve plugin-declared account-owned top-level entries for the brand and
+merge them into an account's SCHEMA.md.
 
-A plugin declares owned top-level account dirs in its PLUGIN.md frontmatter:
+A plugin declares owned top-level account entries in its PLUGIN.md frontmatter,
+by kind:
 
-    account-owned-dirs: [{"dir": "quoting", "description": "..."}]
+    account-owned-dirs:  [{"dir": "quoting", "description": "..."}]
+    account-owned-files: [{"file": "data-portal.json", "description": "..."}]
 
-The owned-dir set for a brand is the union declared by every platform plugin
+The owned-entry set for a brand is the union declared by every platform plugin
 ($PROJECT_DIR/plugins/*/PLUGIN.md) and every premium sub-plugin of a bundle the
 brand ships ($PREMIUM_ROOT/<bundle>/plugins/*/PLUGIN.md, gated by brand.json
 shipsPremiumBundles). Reads PROJECT_DIR from the environment.
 
+A declaration reaches an account only on a brand whose payload carries the
+declaring plugin (brand.json plugins.excluded drops the directory entirely), so
+an entry written by platform code that runs on every brand belongs on a plugin
+no brand excludes, not on the plugin its feature is named after.
+
 The account SCHEMA.md also gains one domain-entity bucket per top-level
 operator-entry node type of the brand's business ontology. That set is derived
 from the brand vertical's schema reference (brand.json#vertical ->
@@ -102,7 +109,17 @@ def _read_vertical(project_dir):
 
 
 def _parse_plugin_md(path):
-    """Return (name, [ {dir, description} ]) from a PLUGIN.md, or (None, [])."""
+    """Return (name, [ {name, kind, description} ]) from a PLUGIN.md, or (None, []).
+    Two frontmatter keys, one list: `account-owned-dirs` yields kind='dir',
+    `account-owned-files` yields kind='file'. A key whose value is not a JSON
+    array of objects is skipped WHOLE: entries are staged and committed only once
+    every element parses, so a bad element cannot half-merge a declaration and
+    leave the rest reporting as strays. The other key and every other plugin
+    still merge, because one hand-edited manifest must never empty the set. A
+    name carrying a path separator is dropped: a fence entry has to match one
+    readdir name, and the region tells a bucket from a file by the trailing slash
+    it adds itself, so a declared `foo/` would render as a bucket that matches
+    nothing."""
     try:
         with open(path) as f:
             text = f.read()
@@ -117,16 +134,21 @@ def _parse_plugin_md(path):
     if nm:
         name = nm.group(1).strip().strip('"').strip("'")
     owned = []
-    om = re.search(r"^account-owned-dirs:\s*(.+)$", fm, re.MULTILINE)
-    if om:
+    for key, field, kind in (("account-owned-dirs", "dir", "dir"),
+                             ("account-owned-files", "file", "file")):
+        om = re.search(r"^" + key + r":\s*(.+)$", fm, re.MULTILINE)
+        if not om:
+            continue
+        staged = []
         try:
-            raw = json.loads(om.group(1).strip())
-            for e in raw:
-                d = (e.get("dir") or "").strip()
-                if d:
-                    owned.append({"dir": d, "description": (e.get("description") or "").strip()})
+            for e in json.loads(om.group(1).strip()):
+                n = (e.get(field) or "").strip()
+                if n and "/" not in n:
+                    staged.append({"name": n, "kind": kind,
+                                   "description": (e.get("description") or "").strip()})
         except Exception:
-            pass
+            continue
+        owned.extend(staged)
     return name, owned
 
 
@@ -158,18 +180,19 @@ def _plugin_md_paths(project_dir):
 
 
 def resolve(project_dir):
-    """Union of owned-dir declarations. First declarer of a dir wins its owner
-    label + description."""
+    """Union of owned-entry declarations. First declarer of a name wins its
+    owner label + description, whichever kind it declared."""
     seen = {}
     order = []
     for path in _plugin_md_paths(project_dir):
         name, owned = _parse_plugin_md(path)
         for e in owned:
-            if e["dir"] in seen:
+            if e["name"] in seen:
                 continue
-            seen[e["dir"]] = {"dir": e["dir"], "description": e["description"], "plugin": name or "unknown"}
-            order.append(e["dir"])
-    return [seen[d] for d in order]
+            seen[e["name"]] = {"name": e["name"], "kind": e["kind"],
+                               "description": e["description"], "plugin": name or "unknown"}
+            order.append(e["name"])
+    return [seen[n] for n in order]
 
 
 def _top_level_labels(schema_path):
@@ -304,7 +327,7 @@ def merge(project_dir, account_dir):
         # entity (non-blank Owner) nests under its owner and is not a target,
         # so a pre-fix account's empty owned bucket prunes while a populated one
         # is kept-and-logged like any other stale bucket.
-        target = FIXED_SEED | {e["dir"] for e in owned} | {b["dir"] for b in domain if _is_root(b["owner"])}
+        target = FIXED_SEED | {e["name"] for e in owned} | {b["dir"] for b in domain if _is_root(b["owner"])}
         # Reconcile existing entries: keep in-target; keep populated strays
         # (logged); drop empty/absent strays (logged).
         new_entries = []
@@ -319,9 +342,9 @@ def merge(project_dir, account_dir):
         # Append newly-projected owned then domain dirs not already present.
         insert = []
         for e in owned:
-            if e["dir"] not in present and e["dir"] not in insert:
-                insert.append(e["dir"])
-                added.append(e["dir"])
+            if e["name"] not in present and e["name"] not in insert:
+                insert.append(e["name"])
+                added.append(e["name"])
         for b in domain:
             if not _is_root(b["owner"]):
                 continue  # contained entity: no root bucket, nests under its owner
@@ -336,16 +359,21 @@ def merge(project_dir, account_dir):
     text = _strip_region(text, MARK_START, MARK_END)
     text = _strip_region(text, ONT_START, ONT_END)
     if owned:
-        region = [MARK_START, "## Plugin-owned top-level workspaces", "",
-                  "A plugin that owns a top-level workspace declares it. The internal",
-                  "structure is owned by that plugin's tools and recreated on the next",
-                  "write. Never reorganise it.", ""]
+        region = [MARK_START, "## Plugin-owned top-level entries", "",
+                  "A plugin declares the account-root entries its feature owns. A",
+                  "directory's internal structure belongs to that plugin's tools and is",
+                  "recreated on the next write, so never reorganise it; a declared file",
+                  "is written whole by its owner. Neither is operator data.", ""]
         for e in owned:
             desc = e["description"] or f"Owned by the {e['plugin']} plugin."
-            region.append(f"- `{e['dir']}/` — {desc}")
+            # The trailing slash marks a bucket. Three readers anchor on it to
+            # tell a directory from a declared file (account-schema-regions,
+            # schema-exposed-dirs.mjs), so a file must never gain one.
+            head = f"{e['name']}/" if e["kind"] == "dir" else e["name"]
+            region.append(f"- `{head}` — {desc}")
         region.append(MARK_END)
         text = text.rstrip("\n") + "\n\n" + "\n".join(region) + "\n"
-    owned_dirs = {e["dir"] for e in owned}
+    owned_dirs = {e["name"] for e in owned if e["kind"] == "dir"}
     # A dir already claimed by a plugin (described in the plugin-owned region)
     # is not also described here, so a name collision cannot double-describe.
     described = [b for b in domain if b["dir"] not in owned_dirs]
@@ -387,8 +415,9 @@ def reconcile(project_dir, account_dir):
             entries, _s, _e = _allowed_block(f.read())
         present = set(entries or [])
     for e in owned:
-        is_present = "true" if e["dir"] in present else "false"
-        print(f"brand={brand} plugin={e['plugin']} ownedDir={e['dir']} present={is_present}")
+        is_present = "true" if e["name"] in present else "false"
+        label = "ownedDir" if e["kind"] == "dir" else "ownedFile"
+        print(f"brand={brand} plugin={e['plugin']} {label}={e['name']} present={is_present}")
     vertical = _read_vertical(project_dir)
     domain = resolve_domain_buckets(project_dir)
     if vertical and not domain:

package/payload/platform/services/claude-session-manager/dist/account-dir-schema-reconcile.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"account-dir-schema-reconcile.d.ts","sourceRoot":"","sources":["../src/account-dir-schema-reconcile.ts"],"names":[],"mappings":"AA2FA,MAAM,WAAW,eAAe;IAC9B,aAAa,EAAE,MAAM,CAAA;IACrB,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,eAAgB,SAAQ,eAAe;IACtD;;;;;0CAKsC;IACtC,UAAU,EAAE,MAAM,EAAE,CAAA;CACrB;AAED;;+DAE+D;AAC/D,wBAAgB,mBAAmB,CACjC,CAAC,EAAE,eAAe,EAClB,WAAW,SAAI,EACf,aAAa,SAAI,EACjB,UAAU,SAAI,GACb,MAAM,CAGR;AAED;;8EAE8E;AAC9E,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAcpE;AA+ED;;;8EAG8E;AAC9E,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,eAAe,CAoCpE;AAED,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,MAAM,CAAA;IACpB,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;CAC/B;AA0DD;;;;;;;;;;;;;iCAaiC;AACjC,wBAAgB,YAAY,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI,CA8DtD;AAED,MAAM,WAAW,yBAAyB;IACxC,KAAK,IAAI,IAAI,CAAA;IACb,IAAI,IAAI,IAAI,CAAA;CACb;AAED;oDACoD;AACpD,wBAAgB,+BAA+B,CAC7C,IAAI,EAAE,aAAa,GAAG;IAAE,UAAU,EAAE,MAAM,CAAA;CAAE,GAC3C,yBAAyB,CAiB3B"}
+{"version":3,"file":"account-dir-schema-reconcile.d.ts","sourceRoot":"","sources":["../src/account-dir-schema-reconcile.ts"],"names":[],"mappings":"AA8EA,MAAM,WAAW,eAAe;IAC9B,aAAa,EAAE,MAAM,CAAA;IACrB,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,eAAgB,SAAQ,eAAe;IACtD;;;;;0CAKsC;IACtC,UAAU,EAAE,MAAM,EAAE,CAAA;CACrB;AAED;;+DAE+D;AAC/D,wBAAgB,mBAAmB,CACjC,CAAC,EAAE,eAAe,EAClB,WAAW,SAAI,EACf,aAAa,SAAI,EACjB,UAAU,SAAI,GACb,MAAM,CAGR;AAED;;8EAE8E;AAC9E,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAcpE;AA+ED;;;8EAG8E;AAC9E,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,eAAe,CAoCpE;AAED,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,MAAM,CAAA;IACpB,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;CAC/B;AA0DD;;;;;;;;;;;;;iCAaiC;AACjC,wBAAgB,YAAY,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI,CA8DtD;AAED,MAAM,WAAW,yBAAyB;IACxC,KAAK,IAAI,IAAI,CAAA;IACb,IAAI,IAAI,IAAI,CAAA;CACb;AAED;oDACoD;AACpD,wBAAgB,+BAA+B,CAC7C,IAAI,EAAE,aAAa,GAAG;IAAE,UAAU,EAAE,MAAM,CAAA;CAAE,GAC3C,yBAAyB,CAiB3B"}

package/payload/platform/services/claude-session-manager/dist/account-dir-schema-reconcile.js

@@ -31,26 +31,24 @@ import { join, relative, sep } from 'node:path';
 import { parseSchemaRegions, HOME_FIXED } from '../../../lib/account-schema-regions/dist/index.js';
 const TAG = '[fs-reconcile]';
 const QUARANTINE_DIR = '.quarantine';
-/** Platform control-plane entries the reconcile NEVER counts as strays, regardless
- *  of what an account's SCHEMA.md allowed set says. provision-account-dir.sh makes
- *  the account dir a git root (`.git`) and writes its hook-enforcement settings
- *  into `.claude/`, and the account's identity lives in account.json. SCHEMA.md is
- *  refreshed on every provision, but an account carrying a stale/older-template/
- *  hand-edited schema whose allowed block omits one of these must not be reported
- *  on every run for machinery it is required to have.
+/** The account's own machinery, which the reconcile NEVER counts as a stray
+ *  whatever that account's SCHEMA.md allowed set says. provision-account-dir.sh
+ *  makes the account dir a git root (`.git`) and writes its hook-enforcement
+ *  settings into `.claude/`; the account's identity lives in account.json;
+ *  AGENTS.md and SCHEMA.md are refreshed on every provision. An account carrying
+ *  a stale, hand-edited or older-template schema must not be reported every run
+ *  for machinery it is required to have.
  *
- *  The second group is platform-written control-plane FILES the platform reads
- *  and writes at the account root every run. Unlike the tool-owned buckets, no
- *  plugin declares them into the SCHEMA.md allowed-top-level block: calendar-
- *  availability.json is the booking page's availability config (quarantining it
- *  froze a live booking page, Task 1877 fix); wa/webchat/telegram-channel-
- *  bindings.json route each channel's inbound; canonical-webchat-session.json
- *  pins the webchat session; session-titles.json holds operator renames. Each is
- *  `join(accountDir, <name>)` in platform code, none is operator data.
- *
- *  Since Task 1899 this belt no longer protects anything from being moved,
- *  because nothing moves. It keeps the account's own machinery out of the stray
- *  count so the standing op=strays line names only what an operator must act on. */
+ *  Feature files at the account root are NOT here. Each is declared by the plugin
+ *  whose feature owns it (Task 1902, `account-owned-files` in PLUGIN.md
+ *  frontmatter), unioned into the account's allowed block by
+ *  platform/scripts/lib/account-schema-owned-dirs.py, and read from there. This
+ *  constant used to hold seven of them and was extended once per casualty
+ *  (calendar-availability.json was Task 1877, after quarantining it froze a live
+ *  booking page; agents-disabled.json was Task 1996), which is the growth the
+ *  declarations replace. setup-account.sh runs the all-accounts merge on every
+ *  install, so a declaration reaches existing accounts and not only fresh ones,
+ *  and the reconcile's ownedFile= lines name any account it has not reached. */
 const PROTECTED_TOP_LEVEL = new Set([
     '.git',
     '.claude',
@@ -58,17 +56,6 @@ const PROTECTED_TOP_LEVEL = new Set([
     'SCHEMA.md',
     'account.json',
     'AGENTS.md',
-    'calendar-availability.json',
-    'wa-channel-bindings.json',
-    'webchat-channel-bindings.json',
-    'telegram-channel-bindings.json',
-    'canonical-webchat-session.json',
-    'session-titles.json',
-    // Task 1996 — names the agents the operator switched off. Platform-written at
-    // the account root every disable, declared by no plugin, so without this every
-    // account with a disabled agent reports it as a stray forever and the standing
-    // line stops naming only what an operator must act on.
-    'agents-disabled.json',
 ]);
 /** Buckets whose depth fs-schema-guard.sh checks, with the same 3-segment cap.
  *  Every other top-level bucket is tool-owned and unbounded — not walked. This