@rubytech/create-sitedesk-code 0.1.508 → 0.1.509

package/payload/platform/plugins/cloudflare/mcp/__tests__/portal-index-push.test.ts

@@ -45,10 +45,20 @@ afterEach(() => rmSync(dir, { recursive: true, force: true }))
 function fakeClient() {
   const calls: { sql: string; params: unknown[] }[] = []
   const rows = new Set<string>()
+  // The pointer is modelled because the flip is read back (Task 1926): a client
+  // that always answers "no pointer" would make every push read as superseded.
+  let pointer: number | null = null
   return {
     calls,
     async query(sql: string, params: unknown[] = []) {
       calls.push({ sql, params })
+      if (/SELECT\s+currentGeneration/i.test(sql)) {
+        return pointer === null ? [] : [{ currentGeneration: pointer }]
+      }
+      if (/INSERT INTO directory_state/i.test(sql)) {
+        pointer = Number(params[1])
+        return []
+      }
       // The open paren is load-bearing: `INSERT INTO directory_state` would
       // otherwise register as a row insert and inflate every count.
       if (/INSERT INTO directory \(/i.test(sql)) {
@@ -308,15 +318,24 @@ function generationClient() {
         })
         return []
       }
+      if (/SELECT\s+MAX\(generation\)/i.test(sql)) {
+        const mine = rows.filter((r) => r.accountId === String(params[0]))
+        return [{ g: mine.length ? Math.max(...mine.map((r) => r.generation)) : null }]
+      }
       if (/DELETE FROM directory\b/i.test(sql)) {
         const g = Number(params[1])
-        // Two DELETE shapes reach this client: the post-flip sweep removes
-        // every OTHER generation (`generation != ?`); the pre-stage clear
-        // (Task 1923) removes exactly THIS generation (`generation = ?`).
-        if (/generation\s*!=\s*\?/i.test(sql)) {
-          for (let i = rows.length - 1; i >= 0; i--) if (rows[i].generation !== g) rows.splice(i, 1)
-        } else {
-          for (let i = rows.length - 1; i >= 0; i--) if (rows[i].generation === g) rows.splice(i, 1)
+        // The post-flip sweep removes strictly OLDER generations
+        // (`generation < ?`, Task 1926). `generation != ?` is the shape it
+        // replaced and `generation = ?` was the Task 1923 pre-stage clear; both
+        // stay modelled so a regression to either shape is visible here.
+        for (let i = rows.length - 1; i >= 0; i--) {
+          const n = rows[i].generation
+          const hit = /generation\s*<\s*\?/i.test(sql)
+            ? n < g
+            : /generation\s*!=\s*\?/i.test(sql)
+              ? n !== g
+              : n === g
+          if (hit) rows.splice(i, 1)
         }
         return []
       }
@@ -374,12 +393,20 @@ function wedgeableClient(seed: { pointer: number; current?: string[]; orphans: s
         rows.push({ accountId, relPath, generation })
         return []
       }
+      if (/SELECT\s+MAX\(generation\)/i.test(sql)) {
+        const mine = rows.filter((r) => r.accountId === String(params[0]))
+        return [{ g: mine.length ? Math.max(...mine.map((r) => r.generation)) : null }]
+      }
       if (/DELETE FROM directory\b/i.test(sql)) {
         const g = Number(params[1])
-        if (/generation\s*!=\s*\?/i.test(sql)) {
-          for (let i = rows.length - 1; i >= 0; i--) if (rows[i].generation !== g) rows.splice(i, 1)
-        } else {
-          for (let i = rows.length - 1; i >= 0; i--) if (rows[i].generation === g) rows.splice(i, 1)
+        for (let i = rows.length - 1; i >= 0; i--) {
+          const n = rows[i].generation
+          const hit = /generation\s*<\s*\?/i.test(sql)
+            ? n < g
+            : /generation\s*!=\s*\?/i.test(sql)
+              ? n !== g
+              : n === g
+          if (hit) rows.splice(i, 1)
         }
         return []
       }
@@ -395,14 +422,18 @@ function wedgeableClient(seed: { pointer: number; current?: string[]; orphans: s
   }
 }
 
-describe('a partial stage self-heals (Task 1923)', () => {
-  it('clears orphans at the next generation, flips onto it, and logs stage-clear', async () => {
-    // Pointer at 5 naming the last good tree; three orphan rows already at
-    // generation 6 for relPaths the current walk re-stages ('output' is the
-    // walk's first row, so the current code's first INSERT is the one that
-    // collides). Without the pre-stage clear that INSERT throws on the UNIQUE
-    // constraint and the push fails, which is what froze gls-data for ~6 h on
-    // 2026-07-22.
+describe('a partial stage self-heals (Task 1923, by the Task 1926 generation claim)', () => {
+  // The wedge: a stage that died mid-batch left rows at current + 1 while the
+  // pointer stayed at current, so every later run recomputed the SAME target
+  // and its first INSERT hit UNIQUE(accountId, relPath, generation). The index
+  // froze at the stale generation until an operator hand-cleared the orphans,
+  // which is what held gls-data for ~6 h on 2026-07-22.
+  //
+  // Task 1923 healed that with a DELETE before the stage. Task 1926 heals it by
+  // claiming above the orphans instead, which needs no DELETE before the flip
+  // at all — and that pre-flip DELETE was the statement a concurrent peer could
+  // aim at the live tree.
+  it('claims above the orphans rather than colliding with them, and sweeps them after the flip', async () => {
     const c = wedgeableClient({
       pointer: 5,
       current: ['output', 'output/report.pdf', 'quotes', 'quotes/CR2969'],
@@ -412,21 +443,20 @@ describe('a partial stage self-heals (Task 1923)', () => {
     const r = await push(c, { log: (l: string) => lines.push(l) })
 
     expect(r.rows).toBe(7)
-    expect(c.pointerValue()).toBe(6)
-    // Nothing survives at a generation the pointer does not name.
-    expect(c.rows.every((row) => row.generation === 6)).toBe(true)
-    const clear = lines.find((l) => l.includes('op=stage-clear'))!
-    expect(clear).toContain('account=acc-1')
-    expect(clear).toContain('generation=6')
-    // Exactly the 3 orphans at generation 6, not the 4 current-tree rows the
-    // pointer names: the clear scopes to `next`, never to a reader-visible row.
-    expect(clear).toContain('cleared=3')
+    // 7, not 6: the orphans sit at 6, so this run claims the one above them.
+    expect(c.pointerValue()).toBe(7)
+    // Nothing survives at a generation the pointer does not name: the sweep
+    // took both the stale tree at 5 and the orphans at 6.
+    expect(c.rows.every((row) => row.generation === 7)).toBe(true)
+    // No statement deletes anything before the flip any more.
+    expect(lines.some((l) => l.includes('op=stage-clear'))).toBe(false)
   })
 
-  it('emits no stage-clear line on a clean cycle with no orphans', async () => {
+  it('re-stages onto a fresh generation with no orphans present', async () => {
     const c = wedgeableClient({ pointer: 5, orphans: [] })
     const lines: string[] = []
     await push(c, { log: (l: string) => lines.push(l) })
+    expect(c.pointerValue()).toBe(6)
     expect(lines.some((l) => l.includes('op=stage-clear'))).toBe(false)
   })
 })
@@ -505,3 +535,215 @@ describe('the index replace is atomic', () => {
     expect(c.calls.filter((x) => /INSERT|DELETE|directory_state/i.test(x.sql))).toEqual([])
   })
 })
+
+// Task 1926. Two pushes of ONE account are reachable: the admin server's 60s
+// loop (pushAllAccounts) and a hand-run `--account <id>` are separate OS
+// processes calling the same pushAccount, so no in-process lock can see both.
+// These tests drive both writers against ONE store and snapshot the reader's
+// view after every statement, so "never a half-built tree" stays a measured
+// property rather than a claim.
+//
+// Statement-level atomicity matches SQLite: each exec() applies whole.
+function sharedStore() {
+  const rows: { accountId: string; relPath: string; generation: number }[] = []
+  let pointer: number | null = null
+  const pointerHistory: number[] = []
+  const snapshots: string[][] = []
+  const deletesAtPointer: number[] = []
+
+  const visible = () =>
+    pointer === null
+      ? []
+      : rows.filter((r) => r.generation === pointer).map((r) => r.relPath).sort()
+
+  // The three DELETE shapes this file can issue. Order matters: `!=` and `<`
+  // must be tested before `=`, or `generation != ?` would read as an equality.
+  const deleteMatcher = (sql: string, g: number) => {
+    if (/generation\s*<\s*\?/i.test(sql)) return (n: number) => n < g
+    if (/generation\s*!=\s*\?/i.test(sql)) return (n: number) => n !== g
+    return (n: number) => n === g
+  }
+
+  return {
+    rows,
+    snapshots,
+    deletesAtPointer,
+    pointerHistory,
+    visible,
+    pointerValue: () => pointer,
+    seed(generation: number, relPaths: string[]) {
+      for (const relPath of relPaths) rows.push({ accountId: 'acc-1', relPath, generation })
+      pointer = generation
+      pointerHistory.push(generation)
+    },
+    async exec(sql: string, params: unknown[] = []) {
+      const out = await (async () => {
+        if (/SELECT\s+currentGeneration/i.test(sql)) {
+          return pointer === null ? [] : [{ currentGeneration: pointer }]
+        }
+        if (/SELECT\s+MAX\(generation\)/i.test(sql)) {
+          const mine = rows.filter((r) => r.accountId === String(params[0]))
+          return [{ g: mine.length ? Math.max(...mine.map((r) => r.generation)) : null }]
+        }
+        if (/INSERT INTO directory_state/i.test(sql)) {
+          const g = Number(params[1])
+          // The upsert's WHERE, modelled: with the guard present the pointer
+          // moves forward only. Without it, every flip lands.
+          const forwardOnly =
+            /excluded\.currentGeneration\s*>\s*directory_state\.currentGeneration/i.test(sql)
+          if (pointer === null || !forwardOnly || g > pointer) {
+            pointer = g
+            pointerHistory.push(g)
+          }
+          return []
+        }
+        if (/INSERT INTO directory \(/i.test(sql)) {
+          const accountId = String(params[0])
+          const relPath = String(params[1])
+          const generation = Number(params[6])
+          if (
+            rows.some(
+              (r) => r.accountId === accountId && r.relPath === relPath && r.generation === generation,
+            )
+          ) {
+            throw new Error(
+              'd1 query failed: HTTP 500 — UNIQUE constraint failed: directory.accountId, directory.relPath, directory.generation',
+            )
+          }
+          rows.push({ accountId, relPath, generation })
+          return []
+        }
+        if (/DELETE FROM directory\b/i.test(sql)) {
+          const g = Number(params[1])
+          const matches = deleteMatcher(sql, g)
+          // The bug's signature: a DELETE that removes rows at the generation
+          // the pointer names is a reader-visible deletion of the live tree.
+          if (pointer !== null && matches(pointer) && rows.some((r) => r.generation === pointer)) {
+            deletesAtPointer.push(pointer)
+          }
+          for (let i = rows.length - 1; i >= 0; i--) if (matches(rows[i].generation)) rows.splice(i, 1)
+          return []
+        }
+        if (/SELECT COUNT/i.test(sql)) {
+          if (/generation\s*=\s*\?/i.test(sql)) {
+            const g = Number(params[1])
+            return [{ n: rows.filter((r) => r.generation === g).length }]
+          }
+          return [{ n: rows.filter((r) => r.generation === pointer).length }]
+        }
+        return []
+      })()
+      snapshots.push(visible())
+      return out
+    },
+  }
+}
+
+/** A one-shot rendezvous: `reached` settles when the writer parks, `open()` frees it. */
+function gate() {
+  let hit!: () => void
+  let open!: () => void
+  const reached = new Promise<void>((r) => (hit = r))
+  const opened = new Promise<void>((r) => (open = r))
+  return { reached, opened, hit: () => hit(), open: () => open() }
+}
+
+/** A client that parks once, either before or after the matching statement. */
+function pausingClient(
+  store: ReturnType<typeof sharedStore>,
+  g: ReturnType<typeof gate>,
+  at: { before?: (sql: string) => boolean; after?: (sql: string) => boolean },
+) {
+  let armed = true
+  const calls: { sql: string; params: unknown[] }[] = []
+  return {
+    calls,
+    async query(sql: string, params: unknown[] = []) {
+      calls.push({ sql, params })
+      if (armed && at.before?.(sql)) {
+        armed = false
+        g.hit()
+        await g.opened
+      }
+      const out = await store.exec(sql, params)
+      if (armed && at.after?.(sql)) {
+        armed = false
+        g.hit()
+        await g.opened
+      }
+      return out
+    },
+  }
+}
+
+const plainClient = (store: ReturnType<typeof sharedStore>) => ({
+  query: (sql: string, params: unknown[] = []) => store.exec(sql, params),
+})
+
+describe('two concurrent pushes of one account (Task 1926)', () => {
+  // The task file's own interleave. B reads the pointer, then stalls. A stages,
+  // flips and sweeps a whole publish. B resumes holding a stale `current`.
+  //
+  // Before the guard: B recomputed next = current + 1 = the generation the
+  // pointer now names, its pre-stage COUNT returned A's live rows, and its
+  // DELETE emptied the tree a client was reading.
+  it('a peer holding a stale pointer never empties or halves the live tree', async () => {
+    const store = sharedStore()
+    store.seed(5, ['output', 'output/report.pdf', 'quotes', 'quotes/CR2969'])
+    const g = gate()
+    const b = pausingClient(store, g, { after: (sql) => /SELECT\s+currentGeneration/i.test(sql) })
+
+    // Captured rather than awaited bare: B throwing for an unrelated reason
+    // would otherwise surface as a passing test.
+    const bRun = push(b, { log: () => {} }).catch((e: unknown) => e)
+    await g.reached
+    await push(plainClient(store), { log: () => {} })
+    g.open()
+    const bResult = await bRun
+
+    expect(bResult).not.toBeInstanceOf(Error)
+    // 4 is the seeded tree, 7 is a complete walk of the fixture. Any other
+    // count is a tree a client could see half-built.
+    expect(store.snapshots.every((s) => s.length === 4 || s.length === 7)).toBe(true)
+    expect(store.deletesAtPointer).toEqual([])
+    expect(store.visible().length).toBe(7)
+    // B resumed holding a stale pointer of 5, saw A's rows at 6 in the MAX, and
+    // claimed 7. Nothing was staged over and nothing was deleted at a live one.
+    expect(store.pointerValue()).toBe(7)
+  })
+
+  // The other order: A stages a whole generation, then stalls before its flip.
+  // B starts fresh, sees A's staged rows in the MAX, claims the generation
+  // above, and publishes. A wakes holding a generation that is now behind.
+  it('a writer overtaken while staging leaves the winner live and says so', async () => {
+    const store = sharedStore()
+    store.seed(5, ['output', 'output/report.pdf', 'quotes', 'quotes/CR2969'])
+    const g = gate()
+    const a = pausingClient(store, g, { before: (sql) => /INSERT INTO directory_state/i.test(sql) })
+    const lines: string[] = []
+
+    const aRun = push(a, { log: (l: string) => lines.push(l) })
+    await g.reached
+    await push(plainClient(store), { log: () => {} })
+    g.open()
+    const aResult = await aRun
+
+    expect(store.snapshots.every((s) => s.length === 4 || s.length === 7)).toBe(true)
+    expect(store.deletesAtPointer).toEqual([])
+    // The pointer never goes backward, which is what keeps the loser harmless.
+    expect(store.pointerHistory).toEqual([...store.pointerHistory].sort((x, y) => x - y))
+    expect(store.pointerValue()).toBe(7)
+
+    const contended = lines.find((l) => l.includes('op=stage-contended'))!
+    expect(contended).toContain('account=acc-1')
+    expect(contended).toContain('generation=6')
+    expect(contended).toContain('pointer=7')
+    expect(contended).toContain('action=superseded')
+    expect(lines.some((l) => l.includes('op=flip'))).toBe(false)
+    // No sweep and no verify from the loser: both would act on, and measure,
+    // the WINNER's tree and report a failure where nothing failed.
+    expect(a.calls.some((c) => /DELETE FROM directory/i.test(c.sql))).toBe(false)
+    expect(lines.some((l) => l.includes('op=verify'))).toBe(false)
+    expect(aResult.superseded).toBe(true)
+  })
+})

package/payload/platform/plugins/cloudflare/skills/data-portal/schema.sql

@@ -150,10 +150,11 @@ CREATE UNIQUE INDEX IF NOT EXISTS auth_attempts_scope_window ON auth_attempts (s
 -- No backfill follows it: the push replaces every row each cycle.
 --
 -- `generation` is which staging round a row belongs to (Task 1910). The push
--- writes the next generation, flips the pointer below in ONE statement, then
--- deletes rows of earlier generations. Uniqueness is scoped by generation
--- because two of them hold the same relPath between the write and the flip;
--- UNIQUE (accountId, relPath) would reject the staged write outright.
+-- claims a generation above every generation the account already holds, writes
+-- the whole tree there, moves the pointer below in ONE forward-only statement,
+-- then deletes strictly older generations (Task 1926). Uniqueness is scoped by
+-- generation because two of them hold the same relPath between the write and
+-- the flip; UNIQUE (accountId, relPath) would reject the staged write outright.
 --   ALTER TABLE directory ADD COLUMN generation INTEGER NOT NULL DEFAULT 0;
 CREATE TABLE IF NOT EXISTS directory (
   id         INTEGER PRIMARY KEY AUTOINCREMENT,

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

@@ -236,8 +236,8 @@ explicit `?plugin=` parameter, not inferred from `--` in the slug.
 
 | Route | Behaviour |
 |-------|-----------|
-| `GET /api/admin/agents` | Session-scoped. Lists the session account's public `agents/*/` dirs (never the `admin` agent), its user-created specialists from `plugins/*/agents/*.md`, and its shipped specialists, each row tagged `kind` and `origin` and carrying `risk`, `worstTool`, `unresolved` and `disabled`. Returns `{agents, accountId, skipped, specialistsSkipped, shippedSkipped}`. 401 when the session maps to no account. |
-| `GET /api/admin/agents/:slug` | Session-scoped. Without `?plugin=` or `?origin=`, returns a public agent's config fields + four owned docs + a `present` map (a missing or unreadable doc is `''`/`present.<role>=false`, never a 500). With `?plugin=`, that plugin's user-created specialist; with `?origin=shipped`, the shipped one. Both specialist shapes add `{risk, worstTool, unresolved, byTool, disabled}`, where `byTool` is one class per declared tool. Selection is explicit rather than inferred, because a premium file and a user-created specialist under a plugin of the same name produce the same slug. Unknown 404s, 401 as above. |
+| `GET /api/admin/agents` | Session-scoped. Lists the session account's public `agents/*/` dirs (never the `admin` agent), its user-created specialists from `plugins/*/agents/*.md`, and its shipped specialists, each row tagged `kind` and `origin` and carrying `risk`, `riskiestTool`, `unresolved` and `disabled`. Returns `{agents, accountId, skipped, specialistsSkipped, shippedSkipped}`. 401 when the session maps to no account. |
+| `GET /api/admin/agents/:slug` | Session-scoped. Without `?plugin=` or `?origin=`, returns a public agent's config fields + four owned docs + a `present` map (a missing or unreadable doc is `''`/`present.<role>=false`, never a 500). With `?plugin=`, that plugin's user-created specialist; with `?origin=shipped`, the shipped one. Both specialist shapes add `{risk, riskiestTool, unresolved, byTool, disabled}`, where `byTool` is one class per declared tool. Selection is explicit rather than inferred, because a premium file and a user-created specialist under a plugin of the same name produce the same slug. Unknown 404s, 401 as above. |
 | `POST /api/admin/agents/:slug/disable?accountId=` | Shipped agents only, enforced here: a slug present in none of the three shipped directories 404s. Moves the file from `specialists/agents/` to `specialists/agents-disabled/` and records the basename in the 0600 store. Returns `{ok, moved}`; `moved:false` means the agent existed only as a bundled template, so nothing was there to move and the store entry is what stops the next provisioning run delivering it. The store is read strictly before anything moves, so an unreadable store 500s with the file untouched rather than rewriting the file whole from an empty set and dropping every other disabled agent. Same `accountId` contract as delete. |
 | `POST /api/admin/agents/:slug/enable?accountId=` | Covers both of disable's outcomes. Returns `{ok, restored}`: a quarantined file moves back (`restored:true`); a bundled-only agent has nothing to move, so clearing the store entry is the whole job (`restored:false`), which is what stops provisioning withholding it. Treating that second case as "nothing to restore" made disable a one-way door. 404 only when neither directory nor store knows the agent. |
 | `DELETE /api/admin/agents/:slug?accountId=` | Public agents only, on the named validated account. Removes the dir after `deleteAgentProjection`; refuses the `admin` slug (403) and a missing/unknown `accountId` (400) with no write. Loud-fail: a graph-cleanup throw aborts the file removal. |
@@ -267,10 +267,15 @@ Agents page survived undiagnosed on a multi-account install.
   `reason=<graph-cleanup-failed|rm-error>` on failure (files preserved on a
   graph-cleanup throw).
 - `op=classify account=<id8> agent=<name> origin=<shipped|public|specialist>
-  risk=<green|amber|red> worstTool=<tool> tools=<n> unresolved=<comma-list|none>
+  risk=<green|amber|red> riskiestTool=<tool> tools=<n> unresolved=<comma-list|none>
   disabled=<bool>` — one line per classified agent per listing, so it fires on
-  every page load. `worstTool` makes a wrong class diagnosable without
-  re-deriving it. **A non-empty `unresolved=` is the one to act on**: the agent
+  every page load. `riskiestTool` makes a wrong class diagnosable without
+  re-deriving it. Its value is the FULL canonical tool name, while the card
+  renders only the segment after the plugin prefix. One load
+  showing `riskiest tool: memory-update` on the card and
+  `riskiestTool=mcp__plugin_memory_memory__memory-update` on this line is the
+  confirmation that both derive from one value.
+  **A non-empty `unresolved=` is the one to act on**: the agent
   is forced red, and the cause is that the built-in table or the registry
   mapping has drifted, not that the agent changed.
 - `op=risk-surface status=load-failed reason=<msg>` — the plugin registry did

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 ]