@rubytech/create-maxy-code 0.1.478 → 0.1.479

package/payload/platform/docs/superpowers/specs/2026-07-20-task-1789-reseat-channel-row-fork-design.md

@@ -0,0 +1,201 @@
+# Task 1789 — Re-seating a channel row forks it to webchat and destroys the channel seat
+
+Design, 2026-07-20.
+
+## The defect
+
+`session-reseat.ts` builds every fork payload with a hardcoded webchat shape. Re-seating a
+WhatsApp or Telegram row therefore spawns a **webchat** session whose `senderId` is
+`session:<newId>`. The per-sender channel server for the real sender is replaced, its SSE stream
+aborts, and `whatsapp/gateway/routes.ts:56` fires `op=channel-detached`. The fork renders with a
+webchat glyph.
+
+The fork is also unreachable from the channel. A sender's session id is
+`adminSessionIdFor(accountId, senderId)` — `sha256` shaped into a v4 UUID, a pure function. Every
+future inbound recomputes the original id, never the fork's.
+
+Observed 2026-07-18 on `sitedesk-code`, account `5e99bba5`, sender `447504472444`, session
+`c6ed890f`. Brand-uniform code path.
+
+## Three corrections to the task brief
+
+The brief was written against a reading of the code that does not hold. All three were confirmed
+by reading the tree and were agreed with the operator before this design was written.
+
+**The seam named in Fix #2 is log-only.** `wa-gateway.ts:312`'s `adminSessionIdFor` call feeds the
+`op=inbound … sessionId=` line and nothing else. The id the spawn actually runs under comes from
+the pure builder `whatsapp/gateway/spawn-request.ts:34`, called once at `server/index.ts:418`.
+Telegram mirrors it exactly (`spawn-request.ts:31`, `server/index.ts:700`). Consulting the
+override at the gateway line alone would make the log truthful and route nothing.
+
+**The fork has no channel binding until the next inbound.** The manager wires the WhatsApp reply
+tool only when a `waChannel` descriptor (senderId, gatewayUrl, serverPath) is present. The re-seat
+route holds none of those, and the manager's store fallback is keyed on the new session id, which
+is empty for a fresh fork. So the fork spawns correctly labelled but without
+`mcp__whatsapp-channel__reply` until an inbound arrives and `ensureChannelSession` binds it. This
+is accepted, not fixed — the existing re-attach path already covers it. It is made observable
+rather than left silent, because the manager's own `op=channel-binding-lost` invariant is gated on
+the store and cannot fire here.
+
+**The audit sweep cannot answer the standing check as specified.** `runDuplicateSenderAudit`
+walks session sidecars on disk. It has no event history, so "a sender whose last event is a
+`channel-detached`" is not derivable from it. The gateway must record detach times for the sweep
+to query.
+
+## Scope
+
+In scope: WhatsApp and Telegram admin channel rows.
+
+Out of scope, deliberately:
+
+- **Public channel rows.** Public sessions key their id on `personId` as well as `senderId`, so
+  the `<channel>:<senderId>` override key is ambiguous for them. Public re-seat is not evidenced
+  as broken. Public rows re-seat exactly as they do today.
+- **Telegram in the standing audit.** `runDuplicateSenderAudit` is WhatsApp-only today. The
+  unseated check extends it in place; making the whole sweep multi-channel is separate work.
+- Everything already listed under the task's own "Out of scope": the fork's displayed model
+  (Task 1790), the cross-lever clobber (Task 940), re-attaching the live sender, and
+  `op=duplicate-sender-sessions` for `447850009518`.
+
+## Design
+
+### Unit 1 — `platform/ui/server/channel-session-override.ts` (new)
+
+Modelled on `canonical-webchat-override.ts`. One JSON file, `channel-session-override.json`, in
+the account directory.
+
+```json
+{ "bySender": { "whatsapp:447504472444": "fc397054-…" } }
+```
+
+- `channelOverridePath(accountDir)` — the file path.
+- `readChannelOverrideId(accountDir, channel, senderId): string | null` — the fork id for that
+  sender, or null when unset, malformed, or not a v4-shaped UUID. Never throws; a corrupt file
+  reads as null so a bad write can never wedge inbound routing.
+- `writeChannelOverrideId(accountDir, channel, senderId, sessionId): void` — merges into
+  `bySender`, preserving other senders' entries. Atomic tmp+rename so a concurrent read never
+  sees a half-written file.
+
+There is no legacy-shape migration. Unlike the canonical override this file has no predecessor.
+
+### Unit 2 — the fork inherits the source row's channel
+
+`session-reseat.ts` reads the source session's `.meta.json` through the existing exported
+`readSidecarMeta`, and passes the result to `resolveReseatPlan` as a new optional `source`
+argument. `resolveReseatPlan` stays pure and unit-testable without the gate.
+
+The channel shape applies when **all three** hold: sidecar `role` is `admin`, sidecar `channel` is
+`whatsapp` or `telegram`, and sidecar `senderId` is a non-empty string. Then the payload carries:
+
+- `channel` — the sidecar's channel
+- `senderId` — the sidecar's senderId
+- `role: 'admin'`
+- `targetAccountId` — the sidecar's `accountId`, when present
+- **no** `webchatChannel` descriptor
+
+`personId` is never carried: the admin-only scope means it is always null on these rows.
+
+When any of the three conditions fails, the payload is byte-for-byte what it is today.
+
+`targetAccountId` is an addition beyond the task text and was approved explicitly. Without it the
+manager defaults the fork to the boot account, so a channel row belonging to a client sub-account
+would fork into the house account — wrong account scope for every Neo4j write the fork makes.
+Pre-983 sidecars carry no `accountId`; those omit the field and keep today's behaviour.
+
+### Unit 3 — resolution consults the override
+
+`buildWaSpawnRequest` and `buildTelegramSpawnRequest` each gain an optional `overrideSessionId`
+input. When set it is used as `sessionId`; otherwise `adminSessionIdFor` as today. The builders
+keep no filesystem access and stay pure.
+
+`server/index.ts` reads the override at both spawn call sites (`:418` WhatsApp, `:700` Telegram),
+resolving the effective account's directory by id through `listValidAccounts()`. Using the
+**effective** account id on the read side matches the write side, which keys on the source
+sidecar's `accountId` — so an account-manager-routed sub-account sender resolves its own override
+and never the house's.
+
+The two gateway `op=inbound` log lines consult the same override, so the logged `sessionId` names
+the session the message actually reaches. The gateways do not read the file themselves: each takes
+an optional `resolveSessionOverride?: (accountId, senderId) => string | null` dependency, injected
+by `server/index.ts` at construction. The gateways keep no filesystem knowledge and stay testable
+with a stub, and an absent dependency degrades to the deterministic id.
+
+### Chained re-seats
+
+Mirroring Task 876's canonical pointer: the route writes the override when the source is either
+the deterministic per-sender id **or** the current override value. Re-seating a fork moves the
+pointer forward instead of stranding it.
+
+### Why not a mutable binding
+
+Rejected, per the task. `adminSessionIdFor`'s determinism is what lets an inbound resume the right
+JSONL after a bridge or manager restart, and every existing channel session's id derives from it.
+
+### Relationship to Task 1746
+
+`spawn-request.ts` currently comments that "the deterministic per-sender id is the ONLY id a
+sender's session ever has", written when Task 1746 removed Task 1526's per-firing seat. That seat
+was **salted per scheduled firing**: it minted a new session on every dispatch, which then
+attached under the sender's own hub key and swallowed their real messages, splitting one
+conversation across two sessions.
+
+This override is a **stable forward pointer**: one session, repointed once by an operator action,
+resolving identically for every subsequent inbound. It cannot split a conversation because it
+never yields a second id for a sender. Both comments are rewritten to say the deterministic id is
+the default rather than the only id, and to record this distinction so the next reader does not
+re-remove the override.
+
+### Unit 4 — observability
+
+- `op=request` gains the source's resolved channel and senderId, so the lifeline says what kind of
+  row was re-seated.
+- `op=channel-forward senderId=… from=… to=…` at the override write, mirroring the existing
+  `op=canonical-forward`.
+- `op=channel-fork-unbound senderId=… session=…` at a channel fork, naming the window in which the
+  fork has no reply tool. The brief did not ask for this; it exists because the manager's own
+  binding-lost invariant provably cannot fire on this path.
+- **Standing check.** The WhatsApp gateway records a detach timestamp per sender when
+  `op=channel-detached` fires, and clears it on attach. `runDuplicateSenderAudit` queries that map
+  and emits `op=sender-unseated senderId=… since=…` for any sender still detached longer than one
+  sweep interval (15 min). This reconciles expected state — every known sender has a seat or a
+  reason not to — against actual, without reproducing the failure. A detached sender with no live
+  channel server is otherwise invisible to action logging, because nothing happens.
+
+### Comments to correct
+
+`session-reseat.ts`'s header (asserts the fork is always webchat-bound),
+`SessionReseatControl.tsx:10-13` (asserts the opposite), and both `spawn-request.ts` Task 1746
+comments. All four must describe the delivered behaviour.
+
+## Testing
+
+- `session-reseat.test.ts` — a `whatsapp` admin sidecar source produces a payload carrying
+  `channel:'whatsapp'`, the source `senderId`, and no `webchatChannel` key; a `telegram` admin
+  sidecar does the same for its channel; a `webchat` sidecar produces today's payload
+  byte-for-byte; a `whatsapp` sidecar with `role:'public'` produces today's payload; a sidecar with
+  no `accountId` omits `targetAccountId`.
+- Override round-trip — write then read returns the fork id for that sender and null for an
+  unwritten sender; a second sender's write preserves the first; a malformed file reads null
+  rather than throwing.
+- Spawn builders — with an `overrideSessionId` the request carries it; without one it carries
+  `adminSessionIdFor`. Both channels.
+- Unseated audit — a sender detached longer than one interval is reported; one detached within the
+  interval is not; one that re-attached is not.
+- Regression proof on-device — re-seat a WhatsApp row, confirm no `channel-detached` without a
+  following `channel-attached`, then send an inbound and confirm `op=inbound … sessionId=<fork>`.
+
+## Files
+
+| File | Change |
+|---|---|
+| `platform/ui/server/channel-session-override.ts` | new |
+| `platform/ui/server/routes/admin/session-reseat.ts` | sidecar read, channel payload, override write, lifeline fields |
+| `platform/ui/app/lib/whatsapp/gateway/spawn-request.ts` | optional `overrideSessionId` |
+| `platform/ui/app/lib/telegram/gateway/spawn-request.ts` | optional `overrideSessionId` |
+| `platform/ui/server/index.ts` | override read at both spawn sites; unseated audit |
+| `platform/ui/app/lib/whatsapp/gateway/wa-gateway.ts` | detach-time map; override in `op=inbound` |
+| `platform/ui/app/lib/telegram/gateway/telegram-gateway.ts` | override in `op=inbound` |
+| `platform/ui/app/lib/whatsapp/gateway/duplicate-sender-audit.ts` | `op=sender-unseated` |
+| `platform/ui/app/components/SessionReseatControl.tsx` | comment correction |
+| `.docs/admin-webchat-native-channel.md` | document the override and the unbound window |
+| `.tasks/LANES.md` | archive sync |

package/payload/platform/docs/superpowers/specs/2026-07-20-task-1818-loop-gate-app-routes-design.md

@@ -0,0 +1,217 @@
+# Task 1818 — Widen the loop gate to cover `app/**` outside `app/lib/`
+
+**Date:** 2026-07-20
+**Lane:** Platform / admin UI · activity view · scheduled work visibility
+**Depends on:** 1810 (landed), 1814 (landed — the widened gate and its marker convention)
+
+## Summary
+
+`scripts/check-loops-registered.mjs` walks `server/**` and `app/lib/**`. The rest of
+`app/**` is unscanned, so a standing server loop armed there would not be caught and
+would be invisible on `/activity`, which is the omission mode 1810 and 1814 exist to
+close.
+
+This task widens the scan to the whole of `app/**` and marks the fifteen browser timers
+already there `loop-exempt:client`.
+
+## Premise corrections
+
+The task file's approach section rests on three factual claims about the tree. All three
+are wrong, and the first one voids one of its two candidate approaches outright. They are
+recorded here because the task's stated reasoning cannot be followed as written.
+
+### 1. There is no Next.js
+
+The task describes the unscanned area as "Next.js route and component code" and names
+`app/api/*/route.ts` as the shape of the loop that would escape.
+
+`platform/ui` has no `next` dependency and no `next.config`. It is a Vite SPA with ten
+HTML entries (`vite.config.ts`) plus a Hono server bundled by tsup from exactly two
+entries, `server/index.ts` and `server/edge.ts` (`tsup.config.ts`). There is no `app/api/`
+directory and no route file under `app/` at all. Server routes live in `server/routes/`,
+which the gate already scans.
+
+The task's second candidate — "treat `app/api/**` and any other server-executing subtree
+as in scope while leaving component directories out" — therefore describes a layout that
+cannot exist in this package. It is void rather than merely less attractive. The task
+states that establishing "whichever the Next.js routing layout actually makes stable" is
+the first work of this task; the answer is that there is no such layout, and the decision
+collapses to the remaining candidate.
+
+### 2. `'use client'` is unusable, but not for the stated reason
+
+The task rules out the `'use client'` directive as a discriminator on the grounds that
+"the 1814 census confirmed `app/lib/use-now-tick.ts` is a React hook carrying no such
+directive".
+
+`app/lib/use-now-tick.ts` carries `'use client'` on line 14, and carried it at 1814's own
+commit (`git show main:…` returns the directive).
+
+The conclusion survives on different evidence. Of the eleven files under `app/` outside
+`app/lib/` that arm a browser timer, three carry no directive: `app/chat/page.tsx`,
+`app/chat/transcript-render.tsx`, and `app/graph/settle-lock.ts`. A discriminator that
+misses three of eleven cannot gate a build.
+
+### 3. Fifteen sites, not sixteen
+
+The task and its LANES row both count sixteen browser timers in the unscanned area.
+
+Applying the gate's own `ARM` regex (`/\bsetInterval\s*\(/`) to `app/**` outside
+`app/lib/`, skipping `__tests__`, yields **fifteen** sites across eleven files. The
+difference is that eight further occurrences are `ReturnType<typeof setInterval>` type
+positions, which have no `(` after the identifier and do not match. The sixteenth timer is
+`app/lib/use-now-tick.ts`, which lives inside a scanned root and already carries its
+marker.
+
+## What the census found
+
+Two findings beyond the count, both bearing on the design.
+
+**No hidden standing loop.** Every one of the fifteen sites is genuinely a browser timer.
+The two least obvious were checked directly: `app/graph/settle-lock.ts` samples
+`network.getPositions()` to freeze vis-network canvas physics and is imported only by
+`app/graph/page.tsx`; `app/chat/transcript-render.tsx` is a React render module ticking
+`setNow(Date.now())`. This is the opposite of 1814, whose widening surfaced
+`visitor-event.ts`, a standing loop that had been invisible the whole time. Here the
+widening surfaces nothing: every new site resolves to a marker, and no `registerLoop` call
+is added, so the registry's 26 production loops are unchanged.
+
+**Server-reachable code outside `app/lib/` already exists.** A census of every
+`from '…/app/…'` import in `server/` returns `app/lib/…` in every case but one:
+`server/routes/whatsapp-reader.ts:43` imports `SUPPORTED_MIME_SET`, `MAX_FILE_BYTES` and
+`MAX_ATTACHMENTS` from `app/admin-types.ts`. Those are runtime values, not types, so this
+is genuinely server-executing code living outside the scanned tree today. It arms no
+timer, so nothing is currently hidden, but the boundary "server code stops at `app/lib/`"
+is already false and the design must not depend on it. No dynamic `import()` or
+`require()` in `server/` reaches `app/`, and no file under `app/` outside `app/lib/`
+imports a `node:` builtin.
+
+## Approach
+
+Scan the whole of `app/**`. Mark the fifteen browser timers `loop-exempt:client`.
+
+Two alternatives were considered and rejected.
+
+**Reachability from the two server entry points.** The gate could resolve the import graph
+from `server/index.ts` and `server/edge.ts` and scan exactly what it reaches. This is the
+most precise statement of the real semantic. It is rejected because it puts a module
+resolver inside a gate whose own header records that hand-rolled parsing is what killed
+its first version: that version stripped `//` comments, ate the closing backtick of every
+template literal containing a URL, and reported `ok` on a real violation. The gate's
+governing principle is to match raw lines and parse nothing.
+
+**Close 1818 as void.** Since there is no route-file surface under `app/` in a Vite SPA, a
+server loop arguably has nowhere there to hide. This is rejected because it rests on
+"everything under `app/` is client today", which is the assumption the task exists to stop
+relying on, and which `app/admin-types.ts` already partially falsifies.
+
+## Design
+
+### The scan root
+
+`SCAN_ROOTS` becomes `['server', 'app']`, replacing `['server', 'app/lib']`.
+
+`app/lib` is subsumed rather than listed alongside `app`. Listing both would walk `app/lib`
+twice and double its contribution to `files=` and `sites=`, corrupting the exact counter
+the task names as its evidence that the widening took effect.
+
+### The fifteen markers
+
+Each site gets `// loop-exempt:client <reason>` on its own line, with the reason specific
+to that timer rather than a repeated phrase. `client` is already in the closed category set
+established by 1814 (`per-connection`, `demand-singleton`, `client`, `registry-primitive`),
+so no convention changes. The task puts the marker convention and category set explicitly
+out of scope.
+
+The sites:
+
+| File | Line | What it ticks |
+|---|---|---|
+| `app/AdminShell.tsx` | 228 | 60s poll |
+| `app/Sidebar.tsx` | 512, 534, 1609 | channel conversations, sessions, system stats |
+| `app/activity/page.tsx` | 428 | 15s activity reload |
+| `app/chat/page.tsx` | 700, 721 | pointer poll, 60s read |
+| `app/chat/transcript-render.tsx` | 80 | 1s relative-time clock |
+| `app/graph/page.tsx` | 1456 | layout poll |
+| `app/graph/settle-lock.ts` | 137 | vis-network motion sampler |
+| `app/hooks/useViewMode.ts` | 110 | view-mode poll |
+| `app/hooks/useVoiceRecorder.ts` | 142 | recording elapsed timer |
+| `app/useAdminAuth.ts` | 219 | auth refresh |
+| `app/useElapsedTimer.ts` | 29, 35 | session tick, elapsed tick |
+
+### The header
+
+The gate's SCOPE block currently reads "Covers `server/**` and `app/lib/**` … NOT covered:
+the rest of `app/**`, which is Next.js route and component code running in the visitor's
+browser". Every clause of that becomes false or was already false.
+
+It is rewritten to state the real boundary (`server/**` and `app/**`, excluding
+`__tests__`), that the server bundles from two entries so `server/**` is where server code
+starts, and that `app/admin-types.ts` is already server-reachable from outside `app/lib/`
+— which is why the whole of `app/` is scanned rather than a subtree of it. A gate whose
+header overclaims is the defect class this file exists to prevent, so the header moves in
+the same change as the behaviour.
+
+### Tests
+
+The behaviour belongs in the project's own committed suite at
+`scripts/__tests__/check-loops-registered.test.ts`, so these are committed rather than
+ephemeral.
+
+One existing test **encodes the hole this task closes**. `ignores files outside the two
+scan roots` (line 87) proves its point with `app/chat/page.tsx`, asserting exit 0 and
+`sites=0`. That file moves in-scope, so the test must be rewritten against a path that is
+genuinely outside both roots, not merely extended around.
+
+New cases:
+
+- An unmarked module-scope `setInterval` in a component file under `app/` outside
+  `app/lib/` fails with exit 1 and the message naming the file.
+- A marked `client` site in that same area passes and is counted under `client=`.
+
+The real-tree floor assertions rise so a walk that silently stops reading shows as
+collapsed counts rather than a healthy `ok`.
+
+### Mutation check
+
+Required by the task on 1814's terms. A real unmarked `setInterval` is inserted into an
+actual file under `app/` outside `app/lib/`, the gate is observed exiting 1 and naming
+that file, and the line is removed. A negative test that passes because the signal is dead
+is the failure this whole line of work exists to remove, and a synthetic fixture under
+`--root` cannot prove the real scan root moved.
+
+## Observability
+
+`files=` rises from **284** to **393**: 109 non-test source files under `app/` outside
+`app/lib/`. The predicted figure is asserted rather than "the number went up", so a partial
+walk fails instead of passing.
+
+`sites=` rises from 10 to 25, `marked=` from 9 to 24, and `client=` from 1 to 16. No
+`registerLoop` call is added, because the census found no standing loop in the newly
+covered area. That pairing — coverage widens, registered loop count holds at 26 — is the
+finding, not an absence of one.
+
+## Scope boundaries
+
+**In scope:** the scan boundary for `app/**` outside `app/lib/`, the marking that decision
+implies, the gate's SCOPE header, and the test surface above.
+
+**Out of scope:** the marker convention and category set, settled in 1814; the two scan
+roots already covered; the gate's raw-line matching, whose two known holes are documented
+in its header and are accepted rather than open.
+
+**Answered, not deferred: `app/admin-types.ts` stays where it is.** Being server-reachable
+from outside `app/lib/` reads at first like a filing error worth correcting. It is not.
+That file exists precisely so it cannot import `app/lib/attachments.ts` — its own comment
+records the reason ("cannot import a Node.js module into a client component"), and
+`attachments.ts` opens with `node:crypto`, `node:fs/promises` and `node:fs`. `app/lib/` is
+the Node-touching tree: 56 of its 191 non-test source files import a `node:` builtin.
+Moving the deliberately client-safe mirror into that directory would file it beside the
+module it exists to avoid. Separately, the move would buy this task's outcome nothing,
+because the widened scan covers the file wherever it lives. So there is no structural
+question left open here and no follow-up task to file.
+
+**A real adjacent risk, named and not fixed here.** `ACCEPT_MIME` / `SUPPORTED_MIME_SET` in
+`app/admin-types.ts` mirror `app/lib/attachments.ts` by hand, with nothing keeping the two
+in sync. That is a mime-allowlist consistency problem with no bearing on loop coverage, and
+it is not touched by this task.

package/payload/platform/docs/superpowers/specs/2026-07-20-task-1819-top-level-label-allowlist-design.md

@@ -0,0 +1,80 @@
+# Task 1819 — top-level label allowlist drift
+
+Design, 2026-07-20.
+
+## Problem
+
+Two tests fail on `main`:
+
+- `server/lib/top-level-labels.test.ts` — deep-equals the derived allowlist against the real references dir
+- `server/routes/__tests__/graph-default-topLevel.test.ts` — resolves the top-level label set for the default view
+
+Both compare the hardcoded client mirror `FILTER_TOP_LEVEL_LABELS` against the set derived from `plugins/memory/references/`.
+
+## Evidence
+
+Measured set diff, both directions:
+
+| Direction | Labels |
+|---|---|
+| In `FILTER_TOP_LEVEL_LABELS`, not in derived | `InboundInvoice` |
+| In derived, not in `FILTER_TOP_LEVEL_LABELS` | none |
+
+Client mirror 48 entries, derived 47. Contributing files: `schema-construction.md`, `schema-estate-agent.md`. Table-derived 14, static 33.
+
+## Cause
+
+Commit `7b225f814` (2026-07-18, "promote ledger labels to base") moved the `InboundInvoice` row out of the `## Top-level node types` table in `schema-construction.md` and into the `## Node Types` table in `schema-base.md`.
+
+`getTopLevelLabelAllowlist` parses only `## Top-level node types` sections. It deliberately never parses `schema-base.md`, because that table mixes child types (`InvoiceLine`, `InvoicePayment`, `PostalAddress`) in with top-level ones. So the promotion deleted `InboundInvoice` from the derived set.
+
+`STATIC_TOP_LEVEL_LABELS` exists precisely for base-schema labels with no top-level section to derive from. `InboundInvoice` was never added to it — `git log -S` confirms the string has never appeared in `top-level-labels.ts`.
+
+The other three promoted labels (`InvoiceLine`, `InvoicePayment`, `Credit`) are documented children in `graph-labels.ts` and correctly stay off both sets.
+
+Nothing regenerates either side. The rot mechanism is that a schema-doc edit in the memory plugin's references directory silently changes the UI's derived chip set, guarded only by a test that was not run before the promotion landed.
+
+## Fix
+
+`InboundInvoice` is genuinely top-level and the client mirror is correct. The derivation is missing an entry.
+
+1. Add `InboundInvoice` to `STATIC_TOP_LEVEL_LABELS`.
+2. Extend the `STATIC_TOP_LEVEL_LABELS` doc comment to cover the reverse migration. It documents only the forward direction today (a vertical gains a top-level section, so its labels leave static). It is silent on the direction that caused this: a label promoted into `schema-base.md` must enter static, because base is never parsed.
+
+Editing either assertion is explicitly not the fix.
+
+## CashEntry
+
+The same commit added `CashEntry`, absent from both sets, so it fails no test but has no `/graph` chip. Operator decision on this sprint: add it as a top-level label.
+
+Justification that it is top-level: the promoting commit describes it as money "not attached to any invoice" with "no parent label". Child labels are reached by drilling down from a parent neighbourhood. `CashEntry` has no parent, so without a chip it is unreachable on `/graph` except by search.
+
+Five surfaces:
+
+| Surface | Change | Gate |
+|---|---|---|
+| `GRAPH_LABEL_COLOURS` | unique hex | hex uniqueness is test-enforced |
+| `LABEL_ICONS` | Lucide glyph | coverage test fails if a colour label has no glyph |
+| `FILTER_TOP_LEVEL_LABELS` | add | client chip mirror |
+| `STATIC_TOP_LEVEL_LABELS` | add | server derived set |
+| `pickShortLabel` | `CashEntry` branch | properties are `entryId`/`direction`/`amount`/`date`/`description`; none match the generic caption keys, so nodes would render captionless |
+
+### Placement
+
+Append `CashEntry` at the end of `GRAPH_LABEL_COLOURS`, not beside the ledger family.
+
+`SHAPE_BY_LABEL` assigns each label a shape by its index position in `ALL_GRAPH_LABELS`, which is the colour table's key order. A mid-table insert shifts every subsequent index and changes the node shape of roughly 40 labels across the whole graph. No test catches that. Appending costs source-file grouping and buys zero collateral churn.
+
+### Build
+
+`platform/lib/graph-style/dist` is a symlink to the parent checkout in this worktree. Replace it with a local build before editing, so the parent checkout's build output is never written to.
+
+## Scope boundaries
+
+**In scope:** the cause of the disagreement, the correct value of the label set, both failing tests, and the five `CashEntry` surfaces.
+
+**Out of scope:** the `/graph` view's rendering; the loop registry and its gate (1810, 1814, 1818); other pre-existing red on `main`; retiring the client mirror in favour of the derived set (already noted as a follow-up in `graph-labels.ts`).
+
+## Testing
+
+The two named tests, passing because the sets agree. Plus the graph-style icon-coverage and hex-uniqueness tests, and the client `graph-labels.test.ts` suite, since the colour table changed.

package/payload/platform/docs/superpowers/specs/2026-07-20-task-1831-data-portal-class-derived-allowlist-design.md

@@ -0,0 +1,163 @@
+# Task 1831 — data portal class-derived allowlist (design)
+
+Date: 2026-07-20. Task: [`.tasks/1831-data-portal-exposes-only-uploads-not-the-sub-accounts-folder-tree.md`](../../../../.tasks/1831-data-portal-exposes-only-uploads-not-the-sub-accounts-folder-tree.md).
+
+## Problem
+
+The portal only shows what the client uploaded. `processFiles`
+(`skills/data-portal/template/functions/api/files.ts:11-24`) reads
+`manifest WHERE ownerId = ?`, and `manifest` holds one row per `/api/upload`
+object. There is no device-to-portal path at all, so an account can receive
+documents from a client but cannot hand any back.
+
+A fixed folder list cannot solve it. On SiteDesk account
+`098a18a3-1741-447f-9778-65470645d57d` the deliverables sit in both `output/`
+and `quotes/`, and `quotes/` is projected per account from the brand's vertical
+ontology (`platform/scripts/lib/account-schema-owned-dirs.py:288-296`), not
+shipped in the template. A different vertical projects different buckets.
+
+Provenance cannot be recovered either. `upsertFileArtifact`
+(`platform/ui/app/lib/file-index.ts:294-307`) stores no writer, and the watcher
+runs agent writes and operator uploads through one path
+(`platform/ui/app/lib/file-watcher.ts:30-34`).
+
+## Approach
+
+Key on each folder's declared class, not its name.
+
+Exposed = the dirs named in the account's `<!-- ontology-buckets -->` region,
+plus `output`, intersected with the ```` ```allowed-top-level ```` block. All
+three are read from `accounts/<accountId>/SCHEMA.md`, which is generated per
+account. A new vertical projects new buckets and they appear with no code change.
+
+## Data flow
+
+```
+DEVICE (each heartbeat)                    D1                     PORTAL
+  read SCHEMA.md
+  resolve exposed dirs
+  walk those dirs only  ── metadata ──▶  directory  ──── read ───▶ folder tree
+                                                                      │
+                                          click a file ───────────────┘
+                                                  │
+                        HEAD (alive?) ◀───────────┤
+                                                  │
+                        signed link, 5 min  ──────┘
+                                  │
+  verify signature ◀──────────────┘
+  re-resolve exposed dirs
+  serve bytes
+```
+
+Bytes never enter D1 or R2. Listing therefore survives the device being offline;
+download does not, and says so plainly.
+
+## Components
+
+| File | Responsibility |
+|---|---|
+| `plugins/cloudflare/bin/schema-exposed-dirs.mjs` | `SCHEMA.md` text in, exposed dir names out. Pure, no I/O. |
+| `plugins/cloudflare/bin/portal-index-push.mjs` | walk exposed dirs, full-replace the account's `directory` rows |
+| `.../template/functions/api/_lib/portal-sign.mjs` | mint + verify the signed link, portal side (sits beside `passcode.mjs`, same precedent) |
+| `plugins/cloudflare/skills/data-portal/schema.sql` | `directory` table, `people.accountId` column |
+| `.../template/functions/api/files.ts` | folder entries beside today's uploads |
+| `.../template/functions/api/download.ts` | uploads to R2 unchanged; indexed files get a signed link |
+| `.../template/portal.js`, `index.html` | breadcrumb folder navigation |
+| `platform/ui/server/routes/portal-fetch.ts` | verify signature, re-resolve exposure, serve |
+
+## Parsing contract
+
+Pinned against the generator, because two details are easy to get wrong and both
+fail silently:
+
+- The ontology region lists `` - `<dir>/` - one folder per <Label> record. `` with
+  an **ASCII hyphen**; the plugin-owned region uses an **em dash**
+  (`account-schema-owned-dirs.py:294` vs `:281`). Parsing on the em dash matches
+  nothing and reads as "this account has no buckets".
+- An absent ontology region is normal, not corrupt: `merge()` strips both regions
+  before regenerating, and a brand with no declared vertical never gets one. It
+  yields `output` alone.
+- A dir claimed by a plugin is described only in the plugin-owned region
+  (`:287`), so it will not parse as a domain bucket and drops out of the exposed
+  set. Instrumented, not fixed, here.
+
+## Authentication
+
+One secret per account, generated at portal assembly, written to the account's
+secrets file and set as the Pages secret `PORTAL_FETCH_SECRET`. The install
+origin is set alongside it as `PORTAL_INSTALL_ORIGIN`.
+
+The portal signs `accountId`, `relPath` and an expiry with HMAC-SHA256 via Web
+Crypto and puts the signature in the link. The install verifies it. The secret
+itself never travels, and each grant covers one file for five minutes.
+
+The install re-resolves the exposed dir list from `SCHEMA.md` on every request
+rather than trusting the path it was handed. A valid signature over
+`documents/private.pdf` is still refused. That check is the security boundary;
+the signature only proves the request came from the portal.
+
+**The two ends do not share a module.** No production code in `platform/ui`
+imports from `platform/plugins` today — only one test does
+(`server/lib/calendar-ics.test.ts:12`) — and this sprint will not invent that
+coupling for fifteen lines of HMAC. The portal mints with
+`_lib/portal-sign.mjs`; `portal-fetch.ts` carries its own verify. Both call Web
+Crypto, which Node 22 and Workers both provide, so the algorithm is identical by
+construction. A parity test mints with the portal module and verifies with the
+install's function, which catches drift at the only place it could occur.
+
+## Error handling
+
+| Condition | Response |
+|---|---|
+| device unreachable (HEAD fails) | 503 `device-offline` |
+| signature absent, altered, or expired | 401 |
+| path outside the exposed dirs | 404, regardless of signature |
+| path outside the account partition | 404 |
+| `SCHEMA.md` missing or unparseable | expose nothing |
+
+The last one deliberately inverts `fs-schema-guard.sh:76-78`, which fails open so
+an unseeded legacy account is not write-blocked. A read surface facing a client
+must fail closed. The code carries that reason inline.
+
+## Testing
+
+Unit only. No portal is deployed anywhere and no account exists on this Mac, so
+nothing can be driven end to end.
+
+- **Resolver.** SiteDesk-shaped text yields `output,quotes`. No ontology region
+  yields `output`. A dir absent from the allowed block is dropped. A region
+  written with an em dash yields zero buckets, which asserts the hyphen contract
+  rather than assuming it. Missing file yields nothing.
+- **Walker.** Fixture tree carrying `output/`, `quotes/`, `documents/`,
+  `uploads/`, `.claude/` produces rows for the first two only, at any depth.
+  Delete leaves no stale row; rename produces one row at the new path; a
+  repeated run is identical.
+- **Listing.** Account A never sees account B's rows. Prefix filtering
+  synthesises directories from paths. A `people` row with no `accountId` returns
+  an empty list, not an error.
+- **Signing.** Round trip verifies. Expired fails. Tampered path fails. Tampered
+  account fails. Parity: a token minted by the portal module verifies with the
+  install's own function, so the two implementations cannot drift unnoticed.
+- **Fetch route.** Well-signed request for a non-exposed path is refused. Path
+  traversal is refused. Exposed path serves with the right content type.
+- **Regression.** The existing 139 tests across 10 files stay green.
+  `typecheck:templates` stays at exit 0.
+
+## Out of scope
+
+The upload ingestion sweep; client write-back, delete or rename; mirroring bytes
+into R2; recording write provenance (the SiteDesk quote engine writes through its
+own tool, not `Write`/`Edit`, so `quotes/` would never register); fixing the
+plugin-owned name collision; search; the `/data` admin browser.
+
+## Dependencies
+
+`people.accountId` is new, so existing enrolments are re-run — the upsert on
+`ownerId` makes that a re-run, not a migration. Each portal-serving account needs
+a seeded `SCHEMA.md` or it exposes nothing. Downloads need the install reachable
+at its tunnel hostname; listing does not.
+
+The heartbeat spawn this copies
+(`plugins/scheduling/mcp/src/scripts/check-due-events.ts:797`) has never been
+observed running on a Pi, which is Task 1828. `portal-index-push.mjs` is
+therefore runnable standalone, so it stays operable while 1828 is open.