@rubytech/create-maxy-code 0.1.478 → 0.1.480

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-1829-platform-ui-typecheck-design.md

@@ -0,0 +1,163 @@
+# Task 1829 — package-wide typecheck for `platform/ui` (design)
+
+**Date:** 2026-07-20
+**Task:** [`.tasks/pending/1829-platform-ui-typechecks-nowhere-so-every-type-contract-is-advisory.md`](../../../../.tasks/pending/1829-platform-ui-typechecks-nowhere-so-every-type-contract-is-advisory.md)
+**Depends on:** 1825 (landed — the narrow loop-contract gate this replaces)
+
+## Problem
+
+Nothing in `platform/ui` runs the TypeScript compiler. `npm run build` is `vite build && tsup`,
+both esbuild-backed, and esbuild strips types without reading them. There is no `lint` script and
+no `typecheck` script. None of the eighteen prebuild gates invokes `tsc`, and no CI workflow does
+either. A type error in this package ships.
+
+Task 1825 built a compile-time contract for the loop-row wire shape, found nothing enforced it, and
+added `scripts/check-loop-contract-types.mjs` — a gate that runs `tsc` and then discards every
+error outside six named files. Six files are gated; roughly three hundred are not.
+
+## Measurements
+
+Every figure below was measured in the task-1829 worktree on 2026-07-20, Node 22.22.0, with
+`platform/node_modules` and `platform/ui/node_modules` symlinked from the parent checkout.
+
+The task file's stated figures do not survive measurement, and three of its premises change as a
+result.
+
+| Quantity | Task file | Measured |
+|---|---|---|
+| `tsc --noEmit` wall time | ~51s | 19s cold, 13s warm |
+| Total errors | 103 | 97 before `build:lib`, 80 after |
+| Error classes | 2 | 3 |
+
+**The sibling `dist/` question is settled: it is a setup problem, not a source problem.** Running
+`npm run build:lib` in `platform/` (clean, 24s) clears all 14 `TS2307` unresolved-import errors. It
+also removes two files from the report entirely — `../lib/graph-search/src/index.ts` and
+`../plugins/memory/mcp/src/tools/memory-delete.ts` — because with the dists present those imports
+resolve to `dist/*.d.ts` rather than dragging the sibling `.ts` sources into the program. So the
+gate's prerequisite is a documented build order, exactly as the task predicted.
+
+**The runtime cost concern dissolves.** At 13–19s there is no case for `--incremental` with a
+cached build-info file, and no case for moving the check to CI. It goes in prebuild.
+
+**There is a third error class the task did not anticipate.** After `build:lib`, the 80 remaining
+errors split three ways:
+
+| Class | Count | Nature |
+|---|---|---|
+| Test-file errors | 62 | Genuine; implicit-`any` params and stale fixtures |
+| Production-file errors, fixable in-tree | 8 | Genuine |
+| `neo4j-driver` v5/v6 type skew | 10 | Cross-package version conflict |
+
+## The `neo4j-driver` skew
+
+`platform/ui` declares `neo4j-driver@^6.0.1`. Thirteen workspace packages under `platform/` declare
+`^5.28.1`, which hoists to `platform/node_modules` as 5.28.3. `platform/lib/*` has no
+`package.json`, so those libs compile against the hoisted v5, while `platform/ui` hands them v6
+`Session` objects. That is the eight `TS2739` and two `TS2345` errors.
+
+It is not a worktree artefact. It reproduces wherever both trees are installed.
+
+At runtime it is currently inert but not honest. `neo4j-driver` is external to the tsup bundle,
+while `platform/lib/*` is inlined into `server.js`. So lib code compiled against v5 types already
+executes against v6 in the server process, and against v5 in each plugin MCP process. Both work
+today.
+
+`platform/ui` has carried `^6` since the fold-in commit; it was never deliberately bumped. It uses
+only `neo4j.int`, `isInt`, `driver`, `auth`, the six temporal `is*` guards, and `type { Session }`.
+Every one exists in v5 — the export diff shows v6 is a strict superset and v5 has nothing v6 lacks.
+
+**Decision: align downward.** `platform/ui` moves to `^5.28.1`. This is one source file, it lands
+`platform/ui` on the same version as the seventeen other packages and as what `platform/lib/*` is
+compiled against, and it stays inside the task's scope boundary. Aligning upward would move every
+platform plugin MCP, service and premium-plugin onto v6 and breach the task's stated out-of-scope
+line; that is its own sprint.
+
+`payload/server/package.json` is generated from `platform/ui/package.json` at bundle time
+(`packages/create-maxy-code/scripts/bundle.js`, `externalDeps`), so the deployed server's driver
+version follows this one file.
+
+## The two production defects
+
+Both were found by the compiler and neither is cosmetic.
+
+**`ChannelIcon` — a live crash.** `GLYPHS` is typed `Record<ReaderChannel, …>` but holds only
+`whatsapp` and `telegram`; `ReaderChannel` is `'whatsapp' | 'telegram' | 'webchat'`. At
+`Sidebar.tsx:1499` a conversation row passes `c.channel`, and `select-sessions.ts:43` states that a
+row can carry any of the three. A webchat row there makes `GLYPHS['webchat']` undefined and `g.fill`
+throws, taking the sidebar subtree with it. `SessionChannelBadge`, in the same file, already routes
+webchat to a globe and unknown tokens to a neutral bubble.
+
+The fix is not to invent a webchat brand path. `ChannelIcon` renders brand glyphs by design, which
+is why `BRAND_CHANNELS` maps only two. Its prop type narrows to the brand channels, and
+`Sidebar.tsx:1499` uses `SessionChannelBadge`, the component built for the all-three case. For
+whatsapp and telegram this is behaviour-preserving; `SessionChannelBadge` delegates to
+`ChannelIcon` at the same size.
+
+**`webchat-gateway` — the type is wrong, not the value.** `public-session-end-review.ts:41` declares
+`dispatchFor: 'eviction' | 'exit'`. The local callback type at `webchat-gateway.ts:83` narrowed it
+to `'eviction'`. Line 422 passing `'exit'` is the documented public-exit path. Widening line 83 is a
+type-only fix with no behaviour change.
+
+## What is built
+
+**Root-cause fixes, 70 errors to 0.** No error is suppressed; each is removed at source.
+
+| Fix | Clears |
+|---|---|
+| `platform/ui/package.json`: `neo4j-driver` `^6.0.1` → `^5.28.1` | 10 |
+| Test files: annotate implicit-`any` params, update stale fixtures | 62 |
+| `sessions.ts` ×4, `whatsapp-reader.ts` ×1 implicit-`any` | 5 |
+| `ChannelIcon` narrowed; `Sidebar.tsx:1499` uses `SessionChannelBadge` | 1 |
+| `webchat-gateway.ts:83` `dispatchFor` widened | 1 |
+| `sidebar-sessions.ts:283` `port` typed `string`, `requirePortEnv` returns `number` | 1 |
+
+**The gate.** `scripts/check-types.mjs` runs `tsc --noEmit` over the whole package and fails on any
+diagnostic. Its ignore list is empty and it says so in its own output, so a future non-zero ignored
+count is visible in build logs rather than inferred.
+
+It keeps both of 1825's blind-pass protections, because they are why that gate could be trusted:
+
+- A diagnostic with no `path(line,col)` prefix means the compiler failed *before* typechecking
+  rather than while typechecking, and is reported as a configuration failure. Exit status cannot
+  carry this distinction — `tsc` exits 2 on a normal run with errors and 1 when it cannot find
+  `tsconfig.json` at all.
+- A non-zero exit with no parseable diagnostic means nothing was typechecked, and fails loudly
+  rather than reporting success.
+
+It adds one pre-flight of its own: the sibling `lib/*/dist` artefacts that `platform/ui` imports
+must exist. If they do not, it exits naming `npm run build:lib` instead of emitting fourteen
+confusing unresolved-import errors. This is the documented build order the task asked for, enforced
+as a state check rather than left in prose.
+
+`check-loop-contract-types.mjs` is deleted. Two gates asserting the same invariant at different
+scopes is the drift 1825 exists to prevent, reintroduced one layer up.
+
+A `typecheck` script is added to `package.json` so the check is runnable on its own.
+
+## Testing
+
+The load-bearing case is a deliberately introduced type error in a file the narrow gate never
+covered. It must be observed failing, and observed passing once removed. A gate that has only ever
+been seen passing has not been shown to work.
+
+Separately, the gate must be shown not to pass blind: pointed at a tree where `tsc` cannot run, it
+exits non-zero rather than reporting success. And the dist pre-flight must be observed firing with a
+lib dist absent.
+
+The `neo4j-driver` downgrade is verified against a running Neo4j, not only against the compiler. A
+dependency change that only ever passed a typecheck has not been shown to work either.
+
+## Scope boundaries
+
+**In scope:** making `tsc` run and pass over `platform/ui`; triaging every pre-existing error;
+retiring the narrow loop-contract gate; aligning `platform/ui` onto `neo4j-driver` v5.
+
+**Out of scope:** the other platform packages (`platform/lib/*`, `platform/plugins/*`), which still
+typecheck nowhere — filed as a follow-up task rather than left as prose. Adding eslint. Changing
+`tsconfig.json` strictness. Moving the seventeen v5 packages to v6. The loop-row contract itself,
+which 1825 closed.
+
+## Observability
+
+None at runtime; this is a build-time contract with no runtime surface. The gate's own output names
+the error count found and the count ignored.