@rubytech/create-maxy-code 0.1.477 → 0.1.479

package/payload/platform/docs/superpowers/specs/2026-07-20-task-1704-data-portal-standing-audit-design.md

@@ -0,0 +1,177 @@
+# Task 1704 — data portal standing audit
+
+**Date:** 2026-07-20 · **Lane:** cloudflare + storage-broker · data-portal observability
+**Depends on:** 1689 (portal, landed), 1694 (broker R2 object ops, landed), 1810 (loop registry, landed)
+
+## The problem
+
+The `[data-portal]` lifeline traces one upload end to end and ends in a re-read post-condition, so
+every failure that emits an event is already covered. Three conditions emit nothing:
+
+- **An orphan object** — an object in R2 with no manifest row. Stored, invisible to ingestion
+  forever, and the upload that produced it returned `200`.
+- **A phantom row** — a manifest row whose object is absent. Ingestion will pull a missing file,
+  and nothing says so until ingestion runs, which may be never.
+- **A stalled ingestion sweep** — an ingestion that never runs logs nothing, so a climbing backlog
+  and an empty one look identical.
+
+Only a standing reconcile reveals any of them. Absence of the audit's line is itself the signal that
+all three are unobservable.
+
+## Premise corrections carried from the task file
+
+The task brief predates three changes. All three point the same way; none change its intent.
+
+1. **The `[storage-audit]` idiom is now `registerLoop`.** Task 1810 moved every standing loop onto
+   `platform/ui/server/loop-registry.ts`, and `scripts/check-loops-registered.mjs` fails the build on
+   a bare `setInterval`. "Copy the `[storage-audit]` shape" therefore means registering a loop, not
+   hand-rolling two unref'd timers.
+2. **Every line number in the brief is stale**, though every cited thing still exists.
+   `runStorageAudit` is `storage-broker.ts:773`; the "silent when the config names no portal" idiom
+   is the `hasBookingSite` check in the availability loop; `r2ObjectList`'s drain-to-exhaustion
+   comment at `cf-exec.ts:443` names this audit as its own reason for existing.
+3. **`reconcilePages` (Task 1728) is a closer template than the brief knew.** It is already a pure
+   orphan/phantom set difference over two lists in `lib/storage-broker/src/audit.ts`, carrying the
+   concurrency contract and the refusal to print `orphan=<everything>` off a failed read. This audit
+   is that shape one level down: objects against rows instead of projects against records.
+
+## Components
+
+### 1. `reconcileDataPortal` — pure, in `lib/storage-broker/src/audit.ts`
+
+Third reconcile beside `reconcileStorage` and `reconcilePages`. It is D1 rows against R2 objects,
+which is that lib's domain, and the ui server imports the lib by source path so there is no dist
+rebuild in the loop.
+
+```ts
+interface DataPortalReconcile {
+  objects: number
+  rows: number
+  orphanObjects: string[]   // object keys with no manifest row
+  phantomRows: string[]     // manifest objectKeys with no object
+  oldestUningestedHrs: number | null   // null renders as `na`
+}
+
+function reconcileDataPortal(
+  objects: Array<{ key: string }>,
+  rows: Array<{ objectKey: string; ingested: number; uploadedAt: string }>,
+  nowMs: number,
+): DataPortalReconcile
+```
+
+`nowMs` is injected so the age arithmetic is deterministic under test rather than clock-dependent.
+
+`oldestUningestedHrs` is computed from rows with `ingested === 0` only, and is `null` when there are
+none. **An `uploadedAt` that will not parse is excluded from the minimum rather than allowed to
+produce `NaN`** — that is the `snapshotAgeMs=NaN` lesson from the availability loop, where a truthy
+but non-ISO value slipped past a `??` guard and logged `NaN`. If exclusion leaves no usable row, the
+result is `null`.
+
+### 2. `parseManifestRows` — pure, exported from the route module
+
+`cf.d1Query` shells `npx wrangler d1 execute --json` and is typed `unknown`. This function parses
+that envelope into the row shape above and **throws on anything it does not recognise**.
+
+Throwing rather than returning `[]` is the load-bearing decision. Zero rows against a populated
+bucket reads as "every object is an orphan" — a fabricated defect count off a failed read, which is
+precisely what `reconcilePages` refuses to print. A throw lands in the d1-degraded branch, where the
+line says the read failed instead of asserting a number it does not have.
+
+### 3. `runDataPortalAudit(root)` — the caller, in `ui/server/routes/storage-broker.ts`
+
+Sits with `runStorageAudit` and `runPagesAudit` at the foot of the same file.
+
+**Discovery.** Walks `data/accounts/*/data-portal.json`. A config that is absent, unparseable, or
+parses but names no `portalDbName` and `bucketName` is **silent** — the `hasBookingSite` idiom. An
+account with no portal is not a fault and must not produce a line.
+
+**It returns before minting a house token when no account has a portal.** Most installs have no data
+portal and no house Cloudflare credential; minting unconditionally would make this loop report an
+error forever on every one of them.
+
+**Reads.** One `makeHouseCfExec(root)` for the whole run, then per account:
+
+- rows — `d1Query(portalDbName, 'SELECT objectKey, ingested, uploadedAt FROM manifest')`
+- objects — `r2ObjectList(bucketName)`
+
+The two halves are caught **separately**, and the line is emitted unconditionally afterwards. This is
+`.tasks/backlog/1351` made structural: the log is not downstream of either read, so neither read can
+skip it. An audit that a data-source failure silences is the same blind spot one layer up, in a task
+that exists because failures emit nothing.
+
+**Degradation.** Each line carries exactly what is still measurable:
+
+| Failure | Line still carries |
+|---|---|
+| R2 read fails | `rows=N oldestUningestedHrs=N`, remainder `na`, `degraded=r2` |
+| D1 read fails | `objects=N`, remainder `na`, `degraded=d1` |
+| Both fail | all `na`, `degraded=d1+r2` |
+
+`oldestUningestedHrs` surviving an R2 failure is not incidental: the backlog age is computable from
+the manifest alone, and it is the one of the three conditions that a half-broken audit can still
+report.
+
+**Line format.** Counts only:
+
+```
+[data-portal-audit] account=<id> objects=N rows=N orphanObjects=N phantomRows=N oldestUningestedHrs=N
+```
+
+Healthy is `orphanObjects=0 phantomRows=0` with a bounded age. **Any non-zero orphan or phantom count
+is a defect, not noise.**
+
+`reconcilePages` reports orphan and phantom *names*, on the grounds that a count says something is
+wrong and a name says what to fix. This audit deliberately does not, and the pure function returning
+the keys does not change that: the keys here are `<ownerId>/<filename>`, real people's filenames,
+and the journal is not where they belong. The task's success criterion specifies counts, and the
+audit owning its own ownership discipline is called out in the brief as load-bearing precisely
+because the in-process path holds the account-wide credential and bypasses `objectGate` entirely.
+
+### 4. Arming, in `ui/server/index.ts`
+
+```ts
+registerLoop({
+  name: 'data-portal-audit',
+  intervalMs: 300_000,
+  firstRunDelayMs: 50_000,
+  run: runDataPortalAuditSafe,
+})
+```
+
+Same interval as the storage and pages audits. The first run is offset past storage (20s), pages
+(35s) and google-account (45s) so a boot does not fire four token mints in the same instant.
+
+**Degradation is not an error.** A degraded run returns a note (`portals=N degraded=M`) and the
+registry records `ok`, because the audit did the job it could and said so. A genuine throw — no
+house credential where a portal exists, an unreachable registry — is logged and **rethrown**, the
+`runStorageAuditSafe` shape, so /activity shows a fresh Last run against a stale Last OK.
+
+## Testing
+
+**Unit, `lib/storage-broker/src/__tests__/audit.test.ts`** — an object with no row counts one
+`orphanObjects`; a row with no object counts one `phantomRows`; a matched pair counts neither;
+`oldestUningestedHrs` comes from the oldest `ingested=0` row; `ingested=1` rows are excluded from it;
+`na` when there are no uningested rows; an unparseable `uploadedAt` does not yield `NaN`.
+
+**Envelope, same run** — `parseManifestRows` on a well-formed wrangler payload, and a throw on a
+malformed one. The throw case is what stops a parse failure reading as an empty manifest.
+
+**Route, new `ui/server/__tests__/data-portal-audit.test.ts`** — modelled on
+`storage-broker-object-routes.test.ts`: `// @vitest-environment node`, `vi.mock` the neo4j store,
+partially mock the lib via `importOriginal`, stub `makeHouseCfExec` with a fake carrying
+`r2ObjectList` and `d1Query`. Cases: two accounts, one with a portal, yields one line; a D1 throw
+still emits a line carrying `degraded=d1`; an R2 throw emits `degraded=r2` with `rows` still counted;
+a malformed D1 payload degrades rather than reporting zero rows; a config naming no portal is silent;
+no portal anywhere mints no token.
+
+**Mutation check** — reverting the reconcile to compare in one direction only must fail the opposite
+direction's test.
+
+## Scope boundaries
+
+**In scope:** the reconcile and its tests, the caller, the arming, the route-level tests, and
+`.docs/data-portal.md` § Observability, which currently states the audit is not built.
+
+**Out of scope:** the device-side ingestion sweep (unbuilt, agent-side); any change to the portal
+template or the gate (1689, landed); escalation beyond a log line — `.tasks/backlog/1351` records
+that a non-zero count escalating nowhere is its own problem, and that is lane-wide, not this task's.

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.