@rubytech/create-sitedesk-code 0.1.509 → 0.1.511

package/payload/platform/docs/superpowers/plans/2026-07-26-task-2023-sidebar-sessions-async-reads.md

@@ -0,0 +1,394 @@
+# Task 2023 — sidebar-sessions async reads Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Stop `computeSessionList` from blocking the one event loop for the whole duration of its filesystem walk, without changing what the endpoint returns.
+
+**Architecture:** The route already sits behind the Task 1986 per-account cache and its compute is already `async` and awaited. The block is not the awaiting; it is that every read inside the compute is synchronous, so the loop cannot run anything else from the first `readFileSync` to the last. Replacing the per-row reads with `node:fs/promises` gives the loop a yield point per row. Directory enumeration is left alone on measurement, not preference (see Global Constraints).
+
+**Tech Stack:** TypeScript, Node 22, Hono, vitest.
+
+## Global Constraints
+
+- **Measured cost split, maxy 2026-07-26, 52 files / 133.9 MB / 38,042 lines, two identical runs:** `enumMs=1`, `readMs=284.5` then `277.4`, `parseMs=212.3` then `216.6`.
+- **The four `readdirSync` calls cost 1 ms and are NOT converted.** `enumerateJsonls` is imported by six other server modules; forking it for 1 ms would trade a measurable regression risk for no measurable gain. This is a deliberate deviation from the task file's problem statement, which names lines 216, 227, 240 and 255 alongside the reads that do cost.
+- **JSON parsing is ~215 ms of pure CPU and no async change removes it.** The deliverable is that it stops arriving as one 215 ms block and arrives as ~52 chunks separated by I/O yields. Do not claim the parse cost is eliminated.
+- **Reads stay sequential.** The current loop holds one `body` at a time and lets it go out of scope each iteration. `Promise.all` over 52 files would hold 133.9 MB at once. Sequential `await` yields the loop without changing the memory profile.
+- **No behaviour change.** Response shape, field values, ordering, census log lines and cache states are all byte-identical.
+- **Existing sync exports keep their signatures.** `enumerateJsonls`, `loadUserTitles`, `readSidecarMeta` and `readBridgeIds` are consumed by `server/index.ts`, `public-reader.ts`, `webchat.ts`, `whatsapp-reader.ts`, `files.ts` and two test files. None of those are in scope.
+- **One parser per format.** Where a sync and an async reader both exist, they share a single exported pure parse function. Two copies of a parse body is a drift registry and is not acceptable.
+
+---
+
+## File Structure
+
+- `server/routes/admin/sidebar-sessions.ts` — the only production file modified. Gains `parseUserTitles`, `parseSidecarMeta`, `loadUserTitlesAsync`, `readSidecarMetaAsync`; `computeSessionList`'s row loop switches to `fs/promises`.
+- `server/routes/admin/__tests__/sidebar-sessions-async-reads.test.ts` — new, holds this task's own tests.
+
+---
+
+### Task 1: Split the two parsers out of their sync readers
+
+**Files:**
+- Modify: `platform/ui/server/routes/admin/sidebar-sessions.ts:308-335` (`loadUserTitles`), `:371-402` (`readSidecarMeta`)
+- Test: `platform/ui/server/routes/admin/__tests__/sidebar-sessions-async-reads.test.ts`
+
+**Interfaces:**
+- Produces: `parseUserTitles(raw: string): Map<string, string>` and `parseSidecarMeta(raw: string): SidecarMeta`. Both take the file's raw text and never touch the filesystem. Both degrade to empty/null on a parse failure or wrong shape, exactly as the current readers do.
+- Consumes: nothing.
+
+- [ ] **Step 1: Write the failing test**
+
+```ts
+import { describe, it, expect } from 'vitest'
+import { parseUserTitles, parseSidecarMeta } from '../sidebar-sessions'
+
+describe('parseUserTitles', () => {
+  it('keeps a trimmed string title and drops every malformed entry', () => {
+    const raw = JSON.stringify({
+      good: { title: '  renamed  ' },
+      blankTitle: { title: '   ' },
+      wrongType: { title: 42 },
+      notAnObject: 'nope',
+      '': { title: 'no id' },
+    })
+    const out = parseUserTitles(raw)
+    expect(out.get('good')).toBe('renamed')
+    expect([...out.keys()]).toEqual(['good'])
+  })
+
+  it('returns an empty map for unparseable or non-object JSON', () => {
+    expect(parseUserTitles('{not json').size).toBe(0)
+    expect(parseUserTitles('[1,2,3]').size).toBe(0)
+    expect(parseUserTitles('null').size).toBe(0)
+  })
+})
+
+describe('parseSidecarMeta', () => {
+  it('reads every field and filters non-string bridgeIds', () => {
+    const raw = JSON.stringify({
+      bridgeIds: ['a', '', 7, 'b'],
+      role: 'admin',
+      channel: 'webchat',
+      senderId: '+447700900000',
+      startedAt: '2026-07-26T00:00:00.000Z',
+      personId: 'p1',
+      adminUserId: 'u1',
+      visitorId: 'v1',
+      agentSlug: 'slug',
+      accountId: 'acct',
+    })
+    expect(parseSidecarMeta(raw)).toEqual({
+      bridgeIds: ['a', 'b'],
+      role: 'admin',
+      channel: 'webchat',
+      senderId: '+447700900000',
+      startedAt: '2026-07-26T00:00:00.000Z',
+      personId: 'p1',
+      adminUserId: 'u1',
+      visitorId: 'v1',
+      agentSlug: 'slug',
+      accountId: 'acct',
+    })
+  })
+
+  it('returns the empty shape for unparseable JSON', () => {
+    expect(parseSidecarMeta('{not json')).toEqual({
+      bridgeIds: [], role: null, channel: null, senderId: null, startedAt: null,
+      personId: null, adminUserId: null, visitorId: null, agentSlug: null, accountId: null,
+    })
+  })
+})
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `cd maxy-code/platform/ui && npx vitest run server/routes/admin/__tests__/sidebar-sessions-async-reads.test.ts`
+Expected: FAIL — `parseUserTitles is not a function` (the export does not exist yet).
+
+- [ ] **Step 3: Write minimal implementation**
+
+Replace the body of `loadUserTitles` from the `JSON.parse` onward with a call to a new exported pure function, and do the same for `readSidecarMeta`. The sync readers keep their exact signatures and their `readFileSync` + catch.
+
+```ts
+/** Pure half of {@link loadUserTitles}: parse the on-disk `session-titles.json`
+ *  text. Shared with the async reader so one format has one parser. */
+export function parseUserTitles(raw: string): Map<string, string> {
+  const out = new Map<string, string>()
+  let parsed: unknown
+  try { parsed = JSON.parse(raw) } catch { return out }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return out
+  for (const [sessionId, value] of Object.entries(parsed as Record<string, unknown>)) {
+    if (!sessionId) continue
+    if (!value || typeof value !== 'object') continue
+    const v = value as { title?: unknown }
+    if (typeof v.title !== 'string') continue
+    const trimmed = v.title.trim()
+    if (!trimmed) continue
+    out.set(sessionId, trimmed)
+  }
+  return out
+}
+
+export function loadUserTitles(accountDir: string | null): Map<string, string> {
+  if (!accountDir) return new Map()
+  let raw: string
+  try { raw = readFileSync(join(accountDir, 'session-titles.json'), 'utf8') } catch { return new Map() }
+  return parseUserTitles(raw)
+}
+```
+
+```ts
+// A factory, not a shared constant. `{ ...CONST }` would copy the REFERENCE to
+// one `bridgeIds` array into every empty result, so a single caller mutating it
+// would corrupt every future empty sidecar in the process.
+function emptySidecarMeta(): SidecarMeta {
+  return {
+    bridgeIds: [], role: null, channel: null, senderId: null, startedAt: null,
+    personId: null, adminUserId: null, visitorId: null, agentSlug: null, accountId: null,
+  }
+}
+
+/** Pure half of {@link readSidecarMeta}: parse a `.meta.json` sidecar's text.
+ *  Shared with the async reader so one format has one parser. */
+export function parseSidecarMeta(raw: string): SidecarMeta {
+  let parsed: unknown
+  try { parsed = JSON.parse(raw) } catch { return emptySidecarMeta() }
+  if (!parsed || typeof parsed !== 'object') return emptySidecarMeta()
+  const r = parsed as { bridgeIds?: unknown; role?: unknown; channel?: unknown; senderId?: unknown; startedAt?: unknown; personId?: unknown; adminUserId?: unknown; visitorId?: unknown; agentSlug?: unknown; accountId?: unknown }
+  const bridgeIds = Array.isArray(r.bridgeIds)
+    ? r.bridgeIds.filter((b): b is string => typeof b === 'string' && b.length > 0)
+    : []
+  return {
+    bridgeIds,
+    role: typeof r.role === 'string' ? r.role : null,
+    channel: typeof r.channel === 'string' ? r.channel : null,
+    senderId: typeof r.senderId === 'string' ? r.senderId : null,
+    startedAt: typeof r.startedAt === 'string' ? r.startedAt : null,
+    personId: typeof r.personId === 'string' ? r.personId : null,
+    adminUserId: typeof r.adminUserId === 'string' ? r.adminUserId : null,
+    visitorId: typeof r.visitorId === 'string' ? r.visitorId : null,
+    agentSlug: typeof r.agentSlug === 'string' ? r.agentSlug : null,
+    accountId: typeof r.accountId === 'string' ? r.accountId : null,
+  }
+}
+
+export function readSidecarMeta(metaPath: string): SidecarMeta {
+  let raw: string
+  try { raw = readFileSync(metaPath, 'utf8') } catch { return emptySidecarMeta() }
+  return parseSidecarMeta(raw)
+}
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `cd maxy-code/platform/ui && npx vitest run server/routes/admin/__tests__/sidebar-sessions-async-reads.test.ts server/routes/admin/__tests__/sidebar-sessions.test.ts server/routes/admin/__tests__/resolve-title.test.ts`
+Expected: PASS on all three files. The two pre-existing files are the regression guard on the sync readers whose bodies just moved.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add maxy-code/platform/ui/server/routes/admin/sidebar-sessions.ts maxy-code/platform/ui/server/routes/admin/__tests__/sidebar-sessions-async-reads.test.ts
+git commit -m "refactor(2023): split the sidecar and user-title parsers out of their sync readers"
+```
+
+---
+
+### Task 2: Add the async readers and switch the row loop onto them
+
+**Files:**
+- Modify: `platform/ui/server/routes/admin/sidebar-sessions.ts:70` (imports), `:572` (`loadUserTitles` call site), `:642-655` (row loop reads)
+- Test: `platform/ui/server/routes/admin/__tests__/sidebar-sessions-async-reads.test.ts`
+
+**Interfaces:**
+- Consumes: `parseUserTitles`, `parseSidecarMeta`, `emptySidecarMeta` from Task 1.
+- Produces: `loadUserTitlesAsync(accountDir: string | null): Promise<Map<string, string>>` and `readSidecarMetaAsync(metaPath: string): Promise<SidecarMeta>`. Same degradation rules as their sync twins.
+
+- [ ] **Step 1: Write the failing test**
+
+The load-bearing assertion is that the loop yields. A test that only checks the returned rows would pass just as well against the synchronous version, which is the dead-signal case of Task 1730. So the test races a timer against the compute: with synchronous reads the timer cannot fire until the walk finishes; with async reads it fires during it.
+
+```ts
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { loadUserTitlesAsync, readSidecarMetaAsync } from '../sidebar-sessions'
+
+let dir: string
+beforeEach(() => { dir = mkdtempSync(join(tmpdir(), 'sbs-async-')) })
+afterEach(() => { rmSync(dir, { recursive: true, force: true }) })
+
+describe('loadUserTitlesAsync', () => {
+  it('reads and parses the same file as the sync twin', async () => {
+    writeFileSync(join(dir, 'session-titles.json'), JSON.stringify({ s1: { title: 'renamed' } }))
+    expect((await loadUserTitlesAsync(dir)).get('s1')).toBe('renamed')
+  })
+
+  it('returns an empty map for a null accountDir and for a missing file', async () => {
+    expect((await loadUserTitlesAsync(null)).size).toBe(0)
+    expect((await loadUserTitlesAsync(join(dir, 'absent'))).size).toBe(0)
+  })
+})
+
+describe('readSidecarMetaAsync', () => {
+  it('reads and parses the same file as the sync twin', async () => {
+    const p = join(dir, 'x.meta.json')
+    writeFileSync(p, JSON.stringify({ role: 'admin', channel: 'webchat' }))
+    const meta = await readSidecarMetaAsync(p)
+    expect(meta.role).toBe('admin')
+    expect(meta.channel).toBe('webchat')
+  })
+
+  it('returns the empty shape for a missing file', async () => {
+    expect((await readSidecarMetaAsync(join(dir, 'absent.meta.json'))).bridgeIds).toEqual([])
+  })
+})
+
+describe('the row loop yields to the event loop', () => {
+  it('lets a pending timer fire while the walk is still running', async () => {
+    const root = join(dir, 'projects', 'slug')
+    mkdirSync(root, { recursive: true })
+    // Bodies large enough that the walk cannot complete inside one tick.
+    const line = JSON.stringify({ type: 'user', message: { role: 'user', content: 'x'.repeat(400) } })
+    for (let i = 0; i < 40; i++) {
+      const id = `0000000${i.toString().padStart(2, '0')}-0000-4000-8000-000000000000`
+      writeFileSync(join(root, `${id}.jsonl`), `${line}\n`.repeat(500))
+    }
+
+    let firedDuringWalk = false
+    const walk = readAllBodiesForTest(join(dir, 'projects'))
+    setTimeout(() => { firedDuringWalk = true }, 0)
+    await walk
+    expect(firedDuringWalk).toBe(true)
+  })
+})
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `cd maxy-code/platform/ui && npx vitest run server/routes/admin/__tests__/sidebar-sessions-async-reads.test.ts`
+Expected: FAIL — `loadUserTitlesAsync is not a function`, and `readAllBodiesForTest is not defined`.
+
+- [ ] **Step 3: Write minimal implementation**
+
+Add the promises import beside the existing sync one, add the two async readers, and export the loop's read half as `readAllBodiesForTest` so the yield test drives the shipped code rather than a hand-copied twin.
+
+```ts
+import { readdirSync, readFileSync, statSync } from 'node:fs'
+import { readFile, stat } from 'node:fs/promises'
+```
+
+```ts
+/** Async twin of {@link loadUserTitles}. Same parser, same degradation. Used by
+ *  computeSessionList so the request path never blocks the loop on this read. */
+export async function loadUserTitlesAsync(accountDir: string | null): Promise<Map<string, string>> {
+  if (!accountDir) return new Map()
+  let raw: string
+  try { raw = await readFile(join(accountDir, 'session-titles.json'), 'utf8') } catch { return new Map() }
+  return parseUserTitles(raw)
+}
+
+/** Async twin of {@link readSidecarMeta}. Same parser, same degradation. */
+export async function readSidecarMetaAsync(metaPath: string): Promise<SidecarMeta> {
+  let raw: string
+  try { raw = await readFile(metaPath, 'utf8') } catch { return emptySidecarMeta() }
+  return parseSidecarMeta(raw)
+}
+
+/** The row loop's read half, exported only so the yield test drives the shipped
+ *  code. Sequential by design: `Promise.all` here would hold every body in
+ *  memory at once (133.9 MB measured on maxy 2026-07-26). */
+export async function readAllBodiesForTest(projectsRoot: string): Promise<number> {
+  let n = 0
+  for (const { path } of enumerateJsonls(projectsRoot)) {
+    try { await readFile(path, 'utf8'); await stat(path); n++ } catch { continue }
+  }
+  return n
+}
+```
+
+In `computeSessionList`, change line 572 and the row loop's reads:
+
+```ts
+  const userTitles = await loadUserTitlesAsync(accountDir)
+```
+
+```ts
+    let body: string
+    let mtimeMs: number
+    try {
+      body = await readFile(path, 'utf8')
+      mtimeMs = (await stat(path)).mtimeMs
+    } catch {
+      continue
+    }
+```
+
+```ts
+    const { bridgeIds, role, channel: sidecarChannel, senderId, personId, adminUserId, accountId: rowAccountId } = await readSidecarMetaAsync(metaPath)
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `cd maxy-code/platform/ui && npx vitest run server/routes/admin/__tests__/sidebar-sessions-async-reads.test.ts`
+Expected: PASS, including the yield test.
+
+- [ ] **Step 5: Mutation-check the yield test**
+
+Temporarily revert `readAllBodiesForTest` to `readFileSync` / `statSync` and re-run. Expected: the yield test FAILS with `firedDuringWalk` false. Restore the async version. A yield test that passes against synchronous reads is measuring nothing.
+
+- [ ] **Step 6: Typecheck and run the full change surface**
+
+Run: `cd maxy-code/platform/ui && npx tsc --noEmit -p tsconfig.json`
+Expected: 0 errors.
+
+Run: `cd maxy-code/platform/ui && npx vitest run server/routes/admin/__tests__/ server/lib/__tests__/route-cache.test.ts server/__tests__/edge-request-timing.test.ts`
+Expected: PASS. `route-cache-watchers.test.ts` fails only when batched with its siblings and passes 4/4 alone; that is Task 2014 and predates this change.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add maxy-code/platform/ui/server/routes/admin/sidebar-sessions.ts maxy-code/platform/ui/server/routes/admin/__tests__/sidebar-sessions-async-reads.test.ts
+git commit -m "perf(2023): read session bodies and sidecars asynchronously so the walk yields the loop"
+```
+
+---
+
+### Task 3: Correct the task file's own criterion and figures
+
+**Files:**
+- Modify: `maxy-code/.tasks/2023-sidebar-sessions-sync-fs-blocks-event-loop.md`
+
+**Interfaces:** none.
+
+- [ ] **Step 1: Replace the p99 verification criterion**
+
+The task says a p99 approaching the request durations confirms and a low p99 refutes. Fourteen consecutive windows measured on maxy read `p99=51` or `52` including one with `max=663`, because one blocked tick out of ~590 samples sits nowhere near the 99th percentile. Rewrite the Observability and Verification sections to turn on `max`, which is the statistic that sees a single sub-second block and which Task 2024 also shipped.
+
+- [ ] **Step 2: Replace the 620 ms figure**
+
+The `p50 620 ms across 27,280 requests` sample is undatable and mostly predates the Task 1986 route cache, which landed 2026-07-25. State the datable post-cache distribution instead: `n=38 p50=2 p90=603 p99=678 max=1161`, and that the cost is one full walk per 30 s poll because the poll interval equals `BACKSTOP_MS`.
+
+- [ ] **Step 3: Record the enumeration deviation**
+
+State that the four `readdirSync` calls were measured at 1 ms and deliberately left synchronous, with the six other importers of `enumerateJsonls` as the reason.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add maxy-code/.tasks/2023-sidebar-sessions-sync-fs-blocks-event-loop.md
+git commit -m "docs(2023): correct the p99 criterion and the pre-cache 620ms figure"
+```
+
+---
+
+## Verification (Phase 4, on-device)
+
+The unit tests prove the loop yields. They cannot prove the lag falls on real data, so the sprint's claim rests on a device reading taken the same way as the before reading:
+
+- Before, already recorded: fourteen windows, `max` 310 to 708 ms in every window containing a `cache=stale-backstop` recompute, `max` 52 to 53 ms in every window without one.
+- After: the same grep across a window of real dashboard traffic. A window containing a `stale-backstop` recompute should no longer show a `max` near the recompute's own `ms=`.
+- Refutation case: if `max` still tracks the recompute duration after the change, the remaining block is the ~215 ms of parsing and the change did not achieve its goal. That is a reportable result, not a failed change.
+
+This step needs an installer publish to reach the device and is therefore operator-gated.

package/payload/platform/docs/superpowers/specs/2026-07-26-task-1902-account-owned-entry-declarations-design.md

@@ -0,0 +1,232 @@
+# Task 1902 — every account-root entry is declared by the component that owns it
+
+Design agreed 2026-07-26. Source task: `.tasks/pending/1902-account-owned-entry-declarations-are-incomplete.md`.
+
+## The problem this removes
+
+`account-schema-owned-dirs.py` unions each plugin's `account-owned-dirs`
+declaration into the account's `SCHEMA.md` `allowed-top-level` block on provision,
+and the standing reconcile
+(`platform/services/claude-session-manager/src/account-dir-schema-reconcile.ts`)
+names every root entry outside that block on the `op=strays` line. Three plugins
+declare anything today: `storage-broker/PLUGIN.md:4` (`pages`),
+`memory/PLUGIN.md:4` (`archive`), and
+`premium-plugins/sitedesk/plugins/sitedesk-job/PLUGIN.md:34` (`quoting`).
+
+Two classes of entry are outside that mechanism.
+
+Platform-written control-plane files at the account root are kept out of the stray
+count by `PROTECTED_TOP_LEVEL`, a hand-maintained constant in the reconcile that
+has been extended once per casualty (`calendar-availability.json` was Task 1877,
+`agents-disabled.json` was Task 1996). It holds seven such files. The mechanism
+that should own them covers directories only, so no plugin can declare a file, and
+`data-portal.json` was never added to either surface and reports as a stray on
+every run.
+
+Directories an agent created at an account root are in no declaration and have no
+writer in the shipped tree. Since Task 1899 removed the move, each costs one
+`op=strays` name per five-minute cycle rather than a broken feature. The cost is a
+permanently noisy signal an operator learns to ignore, which is how the next real
+stray gets missed.
+
+## Evidence
+
+Grep over `platform/plugins`, `platform/scripts`, `platform/services`,
+`platform/templates` and `premium-plugins` for an account-root write of each
+undeclared name:
+
+- `e-sign/` has one writer: `platform/plugins/business-assistant/skills/e-sign/SKILL.md:452`
+  (`mkdir -p "${ACCOUNT_DIR}/e-sign/<DOC_REF>"`), plus the persisted base and the
+  per-signer stamped copies alongside it.
+- `clients`, `workers`, `specs`, `templates`, `sites-staging` and `repo` have no
+  writer. By the source task's own rule an entry with no creator in the tree is
+  agent work product, recorded as such rather than declared.
+
+Writers for the seven protected files and for `data-portal.json`:
+
+| Root file | Writer | Declared on |
+|---|---|---|
+| `calendar-availability.json` | `plugins/scheduling/mcp/src/scripts/publish-availability.ts` | scheduling |
+| `data-portal.json` | `plugins/cloudflare/bin/portal-index-push.mjs` | cloudflare |
+| `wa-channel-bindings.json` | `services/claude-session-manager/src/wa-channel-store.ts` | admin |
+| `telegram-channel-bindings.json` | `services/claude-session-manager/src/telegram-channel-store.ts` | admin |
+| `webchat-channel-bindings.json` | `services/claude-session-manager/src/webchat-channel-store.ts` | admin |
+| `canonical-webchat-session.json` | `ui/server/canonical-webchat-override.ts` | admin |
+| `session-titles.json` | `services/claude-session-manager/src/account-title-stores.ts` | admin |
+| `agents-disabled.json` | `ui/server/routes/admin/agents.ts` | admin |
+
+Six of the eight are written by a shared platform service or the UI server, not by
+the plugin they are declared on. The session manager and the UI server carry no
+manifest the resolver reads, so their files are declared on `admin`, and the rule
+is reach rather than naming: **a declaration is only present on a brand whose
+payload carries the declaring plugin.** `brand.json` `plugins.excluded` drops the
+directory outright (`packages/create-maxy-code/scripts/bundle.js`), and
+`realagent-code` and `property-administrators` both exclude `telegram` while the
+session manager still constructs `TelegramChannelStore`
+(`services/claude-session-manager/src/index.ts`). Declaring
+`telegram-channel-bindings.json` on the telegram plugin would therefore leave
+those two brands reporting it as a stray forever, which is the failure this task
+exists to remove. `admin` is excluded by no brand.
+
+The three remaining declarations sit on the plugin whose own code writes them
+(`scheduling`, `cloudflare`, `business-assistant`). That is self-consistent: when
+such a plugin is excluded, its writer is excluded with it and the file is never
+created, so the declaration is present exactly when the file can be.
+
+`setup-account.sh:69` runs `reconcile_all_accounts_owned_dirs "$ACCOUNTS_DIR"` on
+every install, and that sweep calls `merge_owned_dirs_into_schema` for every
+account carrying an `account.json`. A declaration therefore reaches every existing
+account on the next install, not only accounts provisioned after it lands.
+
+## Units
+
+### 1. `platform/scripts/lib/account-schema-owned-dirs.py`
+
+`_parse_plugin_md` gains a second frontmatter key, `account-owned-files`, parsed
+with the same regex-then-`json.loads` shape as `account-owned-dirs` and keyed
+`file` instead of `dir`:
+
+```
+account-owned-files: [{"file": "data-portal.json", "description": "..."}]
+```
+
+A declaration that fails to parse is skipped and the remaining declarations still
+merge, matching how the dirs key already behaves (`except Exception: pass`).
+
+`resolve` returns one list carrying both kinds, each entry gaining a `kind` field
+of `dir` or `file`, so a single ordered union feeds the merge. Dirs keep their
+existing position ahead of files from the same manifest.
+
+`merge` unions declared file names into the same `allowed-top-level` block as
+dirs. The block is already a flat list of names that carries `SCHEMA.md`,
+`account.json` and `AGENTS.md`, and `parseAllowedTopLevel` in the reconcile
+compares it against `readdirSync` entries without distinguishing files from
+directories, so no consumer changes. The prune rule is unchanged: an entry the
+resolver no longer targets is dropped when empty or absent and kept-and-logged
+when it holds content, and `_dir_holds_files` already treats a non-empty regular
+file as content.
+
+The plugin-owned descriptive region renders a file without the trailing slash a
+directory gets:
+
+```
+- `pages/` — Cloudflare Pages deploy staging for the account's public sites.
+- `data-portal.json` — the account's data-portal index, written by portal-index-push.
+```
+
+`reconcile` prints `ownedFile=<name> present=<true|false>`, the file twin of the
+existing `ownedDir=` line, so a declaration that has not reached an account is
+visible per name.
+
+### 2. Declarations
+
+One frontmatter line added per plugin, in the shape the resolver parses:
+
+- `plugins/business-assistant/PLUGIN.md` — `account-owned-dirs` gains `e-sign`.
+- `plugins/cloudflare/PLUGIN.md` — `account-owned-files` gains `data-portal.json`.
+- `plugins/scheduling/PLUGIN.md` — `calendar-availability.json`.
+- `plugins/admin/PLUGIN.md` — `wa-channel-bindings.json`,
+  `telegram-channel-bindings.json`, `webchat-channel-bindings.json`,
+  `canonical-webchat-session.json`, `session-titles.json`, `agents-disabled.json`.
+
+The resolver reads every `$PROJECT_DIR/plugins/*/PLUGIN.md` present in the
+installed tree, with only premium bundles gated by `shipsPremiumBundles`. A brand
+that excludes a plugin has no manifest to read, which is why the six
+service-written files sit on `admin`: every brand then allows all nine names,
+which is what `PROTECTED_TOP_LEVEL` did for seven of them.
+
+### 3. `platform/services/claude-session-manager/src/account-dir-schema-reconcile.ts`
+
+`PROTECTED_TOP_LEVEL` drops the seven file entries and keeps `.git`, `.claude`,
+`.quarantine`, `SCHEMA.md`, `account.json` and `AGENTS.md`. Its comment is
+rewritten to state the new division: the constant holds the account's own
+machinery, which exists whatever the schema says, and every feature file is held
+by the declaration that owns it.
+
+The behavioural consequence, stated rather than hidden: those seven files are now
+kept out of the stray count by the account's `SCHEMA.md`, not by a constant. An
+account whose schema was never re-merged reports them. The sweep in
+`setup-account.sh` closes that window on the install that ships this change, and
+the `ownedFile=` reconcile line names any account it has not reached.
+
+### 4. Tests
+
+`platform/scripts/__tests__/account-schema-owned-dirs.test.sh` gains, on a
+synthetic tree in the style of the existing shape-b case:
+
+- a plugin declaring `account-owned-files: [{"file": "x.json", ...}]` puts `x.json`
+  in the merged `allowed-top-level` block, describes it in the plugin-owned region
+  without a trailing slash, and reports `ownedFile=x.json present=true` from
+  `reconcile`;
+- a plugin whose `account-owned-files` value is malformed JSON is skipped while a
+  sibling plugin's valid declaration still merges;
+- the merge stays byte-identical on a second run with a file declaration present.
+
+**Mutation check.** Drop the files branch from the resolver and the new cases must
+fail. Revert.
+
+`platform/services/claude-session-manager/src/__tests__/account-dir-schema-reconcile.test.ts`
+carries two tests that prove the code belt: `never counts platform-written
+control-plane root files absent from the allowed block` and `does not count the
+disabled store itself as a stray`. Both seed an account whose `SCHEMA.md` lists no
+such file, which after this change is a stale account rather than a current one.
+They are rewritten to seed the schema a reprovisioned account carries, listing the
+declared file names, and then assert the same outcome: the control-plane files are
+absent from `strayNames` and a genuine operator stray alongside them is still
+counted and named. That is the surface the reconcile reads, so the rewritten tests
+prove the delivered behaviour rather than the retired constant.
+
+### 5. The region parsers and the doc
+
+Three readers parse the plugin-owned region and each anchors on the trailing
+slash inside the backticks: `platform/lib/account-schema-regions/src/index.ts:65`
+(shared by the `/data` page grouping and the reconcile's parity audit) and
+`platform/plugins/cloudflare/bin/schema-exposed-dirs.mjs:42-43` (the public
+data-portal exposure set, which keeps its own copy under a parity test). A file
+line therefore yields no bucket in any of them, which is the required behaviour
+and needs no code change. It is pinned by a case in
+`platform/ui/server/lib/__tests__/account-schema-regions.test.ts`, because a
+future edit relaxing that regex would put a control-plane file in front of a
+client.
+
+`.docs/data-portal-folder-index.md` is the authoritative description of how the
+allowed set is built and currently describes plugin-owned as directories. It
+gains the second kind and the trailing-slash rule.
+
+## Scope boundaries
+
+### In scope
+
+Units 1 to 5.
+
+### Out of scope
+
+- Reprovisioning the laptop's accounts, and the two device checks that depend on
+  it (`op=strays` naming only recorded work product, and the negative check that
+  removing one declaration makes its entry reappear). Both need this change
+  published and installed, and publish awaits an explicit operator command. Task
+  `2027-reprovision-laptop-accounts-after-1902-declarations.md`.
+- Declaring `clients`, `workers`, `specs`, `templates`, `sites-staging` or `repo`.
+  No shipped component writes them, so declaring them would make the allowed list
+  a record of what happens to exist rather than of what is owned. They continue to
+  appear in `op=strays`, which is the correct report for debris.
+- Relocating agent work product into schema buckets. Task 1894 covers the glsmith
+  case.
+- Teaching `fs-schema-guard.sh` to tell a declared file from an operator bucket.
+  The guard reads the same `allowed-top-level` fence as an allow-list for
+  `Write`/`Edit`/`NotebookEdit`, so declaring these eight files makes them
+  agent-writable where they were blocked before. Measured: the same envelope
+  returns exit 2 against the pre-merge schema and exit 0 against the merged one.
+  The fence already permits `account.json`, `SCHEMA.md`, `secrets/` and
+  `.claude/`, so it is a layout guard rather than a trust boundary, and this
+  widens it rather than breaches it. Task
+  `2028-fs-schema-guard-cannot-tell-a-declared-file-from-an-operator-bucket.md`.
+- The reconcile's report-only posture. Task 1899 settled it.
+
+## Observability
+
+The `op=strays` line from Task 1899 is the instrument. A declared entry never
+appears in it, so anything that does is either debris or an undeclared owner, and
+the two are separated by asking what created it. The `ownedDir=` and `ownedFile=`
+lines from `reconcile` are the second instrument: they name, per account, a
+declaration that has not yet reached that account's `SCHEMA.md`.