@rubytech/create-maxy-code 0.1.478 → 0.1.480

package/payload/platform/docs/superpowers/plans/2026-07-20-task-1829-platform-ui-typecheck.md

@@ -0,0 +1,830 @@
+# Task 1829 — package-wide typecheck for `platform/ui` (implementation plan)
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Make a type error anywhere in `platform/ui` fail the build, with an empty ignore list.
+
+**Architecture:** The gate is built first and used as the measuring instrument for every
+subsequent task — it starts red at 70 errors and each task drives the count down. It is wired into
+`prebuild` only in the final task, so the build is never left broken mid-plan. Every error is
+removed at source; none is suppressed.
+
+**Tech Stack:** TypeScript 5.7, `tsc --noEmit`, Node 22.22.0, vitest 4, plain `.mjs` gate scripts
+invoked from `prebuild`.
+
+## Global Constraints
+
+- Work in `maxy-code/platform/ui` inside the worktree at
+  `/Users/neo/getmaxy/maxy-code/.claude/worktrees/task-1829-platform-ui-typecheck`.
+- Node 22.22.0. Confirm with `node -v` before any `tsc` or `vitest` run.
+- `platform/node_modules` and `platform/ui/node_modules` are symlinks into the parent checkout.
+  Never run `npm install` in `platform/ui` — it would mutate the parent's dependency tree. The
+  neo4j-driver change in Task 2 is applied to the shadow tree instead; the recipe is in that task.
+- The sibling `platform/lib/*/dist` artefacts must exist before `tsc` runs. `npm run build:lib`
+  from `platform/` produces them, clean, in about 24 seconds.
+- Baseline: **80 errors**, measured after `build:lib` with `platform/ui` still resolving
+  neo4j-driver to v6. Task 2 takes it to 70. Every task states the count it must leave behind, and
+  they chain: 80 → 70 → 62 → 59 → 20 → 0.
+- No error is ever silenced with `@ts-ignore`, `@ts-expect-error`, `any`, or a `tsconfig` exclusion.
+  If a fix looks like it needs one, stop and raise it.
+- Commit after each task with a `Session: 25c26868-c975-4386-b247-a6aa53f33090` trailer and
+  `Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>`.
+
+---
+
+### Task 1: The gate script — the failing test
+
+Build the instrument before the work. It must be observed red at 70 before anything is fixed.
+
+**Files:**
+- Create: `platform/ui/scripts/check-types.mjs`
+- Modify: `platform/ui/package.json` (add `typecheck` script only; prebuild is untouched until Task 9)
+
+**Interfaces:**
+- Produces: `scripts/check-types.mjs`, runnable as `node scripts/check-types.mjs` from
+  `platform/ui`. Exit 0 when `tsc --noEmit` emits no diagnostic; exit 1 otherwise.
+
+- [ ] **Step 1: Write the gate**
+
+Create `platform/ui/scripts/check-types.mjs`:
+
+```javascript
+#!/usr/bin/env node
+
+// Task 1829 — prebuild gate: the whole package must typecheck.
+//
+// Nothing in platform/ui ran the TypeScript compiler until this gate existed.
+// `npm run build` is `vite build && tsup`, both esbuild-backed, and esbuild
+// strips types without reading them. There is no lint script and no CI job that
+// runs the compiler, so a type error in this package shipped.
+//
+// This replaces scripts/check-loop-contract-types.mjs (Task 1825), which ran the
+// compiler and then discarded every error outside six named files. That was the
+// right scope for one page's contract and the wrong shape for a package: six
+// files were gated and roughly three hundred were not. Two gates asserting the
+// same invariant at different scopes is the drift 1825 exists to prevent, so
+// that gate is deleted rather than kept alongside this one.
+//
+// THE IGNORE LIST IS EMPTY, and this gate says so on every run. A gate that
+// starts life with a long ignore list is a gate nobody trusts. The ignored count
+// is printed so that if one is ever added, its growth is visible in build logs
+// rather than inferred.
+
+import { spawnSync } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { resolve, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const UI_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+
+// Pre-flight 1: the sibling lib artefacts this package imports.
+//
+// platform/ui imports built sibling libs by relative path into `dist/`. Those
+// are build outputs, gitignored, and absent in a fresh clone or worktree. With
+// them missing the compiler reports fourteen unresolved-import errors that look
+// like source defects and are not — the fix is a build order, not a code change.
+// Checking the artefacts directly turns that into one actionable line.
+const REQUIRED_LIB_DISTS = ['active-rules', 'graph-style', 'graph-trash', 'graph-write', 'ledger-core']
+const missingDists = REQUIRED_LIB_DISTS.filter(
+  (lib) => !existsSync(resolve(UI_ROOT, '..', 'lib', lib, 'dist', 'index.js')),
+)
+if (missingDists.length > 0) {
+  console.error(
+    `[check-types] error lib-dist-missing libs=${missingDists.join(',')}\n` +
+      '  These are build outputs, not source. Run `npm run build:lib` from platform/ first.\n' +
+      '  Without them tsc reports unresolved-import errors that are a build order problem,\n' +
+      '  not a type error, and this gate will not guess which it is looking at.',
+  )
+  process.exit(1)
+}
+
+// Pre-flight 2: the compiler itself.
+const tsc = resolve(UI_ROOT, 'node_modules', '.bin', 'tsc')
+if (!existsSync(tsc)) {
+  console.error(
+    `[check-types] error tsc-not-found path=${tsc}\n` +
+      '  Run `npm install` in platform/ui. This gate cannot check types without the compiler.',
+  )
+  process.exit(1)
+}
+
+const run = spawnSync(tsc, ['--noEmit'], { cwd: UI_ROOT, encoding: 'utf8' })
+
+if (run.error) {
+  console.error(`[check-types] error tsc-spawn-failed ${run.error.message}`)
+  process.exit(1)
+}
+
+// tsc writes diagnostics to stdout. A per-file diagnostic is
+// `path(line,col): error TSxxxx: msg`. A configuration or invocation failure
+// (TS5058, TS18003, a malformed tsconfig) has no `path(line,col)` prefix, and
+// when tsc cannot find a project at all it prints help text and emits no
+// diagnostics whatsoever.
+//
+// That distinction is what stops this gate passing blind, and exit status cannot
+// carry it: tsc exits 2 on a normal run that found type errors, and 1 when it
+// cannot locate tsconfig.json. A gate keyed on the status code would read the
+// catastrophe as the milder case. What separates them is whether the compiler
+// produced any parseable diagnostic — a run that found nothing to say AND failed
+// did not typecheck anything.
+const DIAGNOSTIC = /^(.+?)\((\d+),(\d+)\): error TS\d+: /
+const lines = `${run.stdout ?? ''}${run.stderr ?? ''}`.split('\n')
+const errorLines = lines.filter((l) => DIAGNOSTIC.test(l))
+const fatalLines = lines.filter((l) => / error TS\d+: /.test(l) && !DIAGNOSTIC.test(l))
+
+if (fatalLines.length > 0) {
+  console.error('[check-types] error tsc-configuration-failed')
+  for (const l of fatalLines) console.error(`  ${l}`)
+  console.error(
+    '\n  The compiler reported an error with no source location, which means it failed before\n' +
+      '  typechecking rather than while typechecking. The package has NOT been checked.',
+  )
+  process.exit(1)
+}
+
+if (run.status !== 0 && errorLines.length === 0) {
+  console.error(
+    `[check-types] error tsc-produced-no-diagnostics status=${run.status}\n` +
+      '  tsc exited non-zero and emitted no parseable diagnostic, so it did not typecheck the\n' +
+      '  package — most likely tsconfig.json is missing or the invocation is wrong. The package\n' +
+      '  has NOT been checked.',
+  )
+  if (run.stdout) console.error(`  first output line: ${run.stdout.split('\n')[0]}`)
+  process.exit(1)
+}
+
+if (errorLines.length > 0) {
+  console.error(`[check-types] FAIL errors=${errorLines.length} ignored=0`)
+  for (const l of errorLines) console.error(`  ${l}`)
+  console.error(
+    '\n  platform/ui does not typecheck. Fix the type — do not widen it, cast it away, or add\n' +
+      '  an ignore entry to this gate.',
+  )
+  process.exit(1)
+}
+
+console.log(`[check-types] ok errors=0 ignored=0 tsc-status=${run.status}`)
+```
+
+- [ ] **Step 2: Add the `typecheck` script**
+
+In `platform/ui/package.json`, add to `scripts`, immediately after `"tokens"`:
+
+```json
+    "typecheck": "node scripts/check-types.mjs",
+```
+
+Leave `prebuild` alone. It still ends in `check-loop-contract-types.mjs` until Task 9.
+
+- [ ] **Step 3: Restore the v6 driver so the baseline is honest**
+
+The investigation left `platform/ui/node_modules` as a shadow tree with the v6 driver omitted, to
+prove the downgrade clears 10 errors without installing into the parent. Task 2 is where that
+becomes real. For this task's baseline, put it back to the plain parent symlink:
+
+```bash
+cd maxy-code/platform/ui
+rm -rf node_modules
+ln -sfn /Users/neo/getmaxy/maxy-code/platform/ui/node_modules node_modules
+node -p "require.resolve('neo4j-driver', {paths:[process.cwd()+'/app/lib']})"
+```
+Expected: the resolve path ends `platform/ui/node_modules/neo4j-driver/lib/index.js` — the v6 copy.
+
+- [ ] **Step 4: Build the sibling libs, then run the gate to verify it fails**
+
+Run:
+```bash
+cd maxy-code/platform && npm run build:lib
+cd ../ui && npm run typecheck
+```
+Expected: exit 1, first line `[check-types] FAIL errors=80 ignored=0`.
+
+If the count is not 80, stop — the baseline has moved and the rest of this plan's counts are wrong.
+
+- [ ] **Step 5: Verify the dist pre-flight fires**
+
+Run:
+```bash
+mv ../lib/graph-style/dist ../lib/graph-style/dist.bak && npm run typecheck; echo "exit=$?"
+mv ../lib/graph-style/dist.bak ../lib/graph-style/dist
+```
+Expected: exit 1, `[check-types] error lib-dist-missing libs=graph-style`, and no tsc diagnostics printed.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add maxy-code/platform/ui/scripts/check-types.mjs maxy-code/platform/ui/package.json
+git commit -m "feat(1829): package-wide typecheck gate, not yet wired into prebuild"
+```
+
+---
+
+### Task 2: Align `neo4j-driver` onto v5 — clears 10
+
+`platform/ui` declares `^6.0.1`; the seventeen other packages and everything `platform/lib/*`
+compiles against declare `^5.28.1`. `platform/ui` hands v5-typed lib functions its v6 `Session`
+objects, which is the eight `TS2739` and two `TS2345`.
+
+**Files:**
+- Modify: `platform/ui/package.json:39`
+
+**Interfaces:**
+- Produces: `platform/ui` resolving `neo4j-driver` to the same 5.28.3 copy at
+  `platform/node_modules` that `platform/lib/*` compiles against.
+
+- [ ] **Step 1: Change the declared version**
+
+In `platform/ui/package.json`, change:
+
+```json
+    "neo4j-driver": "^6.0.1",
+```
+to:
+```json
+    "neo4j-driver": "^5.28.1",
+```
+
+- [ ] **Step 2: Make the installed tree match the declaration**
+
+`npm install` here would write into the parent checkout, because `platform/ui/node_modules` is a
+symlink to it. Build a shadow instead: a real directory of per-entry symlinks into the parent, with
+the three v6 driver packages omitted so resolution walks up to `platform/node_modules` and finds
+5.28.3. This is worktree-local and leaves the parent untouched.
+
+```bash
+cd maxy-code/platform/ui
+P=/Users/neo/getmaxy/maxy-code
+rm node_modules && mkdir node_modules
+for e in "$P/platform/ui/node_modules"/*; do
+  b=$(basename "$e")
+  case "$b" in neo4j-driver|neo4j-driver-core|neo4j-driver-bolt-connection) continue;; esac
+  ln -s "$e" "node_modules/$b"
+done
+for e in "$P/platform/ui/node_modules"/.[!.]*; do
+  ln -s "$e" "node_modules/$(basename "$e")" 2>/dev/null || true
+done
+node -p "require.resolve('neo4j-driver', {paths:[process.cwd()+'/app/lib']})"
+```
+Expected: the resolve path ends `platform/node_modules/neo4j-driver/lib/index.js`.
+
+This shadow is a worktree artefact, not a deliverable. On a real checkout the equivalent is
+`npm install` honouring the changed `package.json`. Say so in the debrief — the landed change is one
+line of `package.json`, and whoever installs next gets v5 from npm.
+
+- [ ] **Step 3: Run the gate**
+
+Run: `npm run typecheck`
+Expected: exit 1, `[check-types] FAIL errors=70 ignored=0`. Confirm no `TS2739` or `TS2345`
+mentioning `neo4j-driver-core` remains.
+
+- [ ] **Step 4: Verify against a running Neo4j, not just the compiler**
+
+A dependency change that only ever passed a typecheck has not been shown to work. Exercise the
+driver against the live database:
+
+```bash
+cd maxy-code/platform/ui
+npx vitest run app/lib/__tests__/graph-write-gate.test.ts app/lib/__tests__/graph-health-audits.test.ts
+```
+Expected: all pass.
+
+Then drive a real query through the v5 driver using the same API surface `platform/ui` uses
+(`neo4j.driver`, `neo4j.auth`, `neo4j.int`, `session.run`):
+
+```bash
+node --input-type=module -e "
+import neo4j from 'neo4j-driver'
+const uri = process.env.NEO4J_URI ?? 'bolt://127.0.0.1:7687'
+const d = neo4j.driver(uri, neo4j.auth.basic(process.env.NEO4J_USER ?? 'neo4j', process.env.NEO4J_PASSWORD))
+const s = d.session()
+const r = await s.run('RETURN \$n AS n', { n: neo4j.int(42) })
+console.log('driver', neo4j.driver.name ? 'ok' : 'ok', 'value=', r.records[0].get('n').toString())
+await s.close(); await d.close()
+"
+```
+Expected: `value= 42`. If the local Neo4j is not running or credentials are absent, say so
+explicitly in the debrief rather than recording this step as passed.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add maxy-code/platform/ui/package.json
+git commit -m "fix(1829): align platform/ui onto neo4j-driver v5, matching the libs it calls"
+```
+
+---
+
+### Task 3: Production type-truth fixes — clears 8
+
+Three of these are defects the compiler found, not annotations. Read each before changing it.
+
+**Files:**
+- Modify: `platform/ui/app/components/ChannelIcon.tsx:8,14`
+- Modify: `platform/ui/app/Sidebar.tsx:1499`
+- Modify: `platform/ui/app/lib/webchat/gateway/webchat-gateway.ts:83`
+- Modify: `platform/ui/server/routes/admin/sidebar-sessions.ts:283`
+- Modify: `platform/ui/server/routes/admin/sessions.ts:638,667,702`
+- Modify: `platform/ui/server/routes/whatsapp-reader.ts:1144`
+
+- [ ] **Step 1: Fix the `ChannelIcon` crash**
+
+`GLYPHS` is `Record<ReaderChannel, …>` but holds two of the three channels. `ReaderChannel` is
+`'whatsapp' | 'telegram' | 'webchat'`. A webchat row at `Sidebar.tsx:1499` makes `GLYPHS['webchat']`
+undefined and `g.fill` throw.
+
+Do not invent a webchat brand path. `ChannelIcon` renders brand glyphs by design, which is why
+`BRAND_CHANNELS` in the same file maps only two. Narrow its type instead.
+
+In `app/components/ChannelIcon.tsx`, add the brand-channel type above `GLYPHS` and use it:
+
+```tsx
+// ChannelIcon renders inlined brand marks, and only WhatsApp and Telegram have
+// one. Webchat and any future channel are the SessionChannelBadge's job — it
+// routes webchat to a globe and unknown tokens to a neutral bubble. Typing
+// GLYPHS as Record<ReaderChannel, …> claimed a webchat glyph existed; it did
+// not, and a webchat row reaching here threw on `g.fill`.
+type BrandChannel = Extract<ReaderChannel, 'whatsapp' | 'telegram'>
+
+const GLYPHS: Record<BrandChannel, { fill: string; path: string; label: string }> = {
+```
+
+and change the component's prop type:
+
+```tsx
+export function ChannelIcon({ channel, size = 16 }: { channel: BrandChannel; size?: number }) {
+```
+
+and the badge's lookup map, which was already brand-only in fact:
+
+```tsx
+const BRAND_CHANNELS: Record<string, BrandChannel> = { whatsapp: 'whatsapp', telegram: 'telegram' }
+```
+
+- [ ] **Step 2: Route the conversation row through the badge**
+
+`Sidebar.tsx:1499` passes `c.channel`, typed `ReaderChannel`, which now no longer fits.
+`SessionChannelBadge` is the component built for the all-three case and delegates brand channels to
+`ChannelIcon` at the same size, so whatsapp and telegram render unchanged.
+
+In `app/Sidebar.tsx:1499`, change:
+
+```tsx
+                <ChannelIcon channel={c.channel} size={14} />
+```
+to:
+```tsx
+                <SessionChannelBadge channel={c.channel} size={14} />
+```
+
+`SessionChannelBadge` is already imported on line 6. Leave line 1031 alone — it maps over
+`READER_CHANNELS`, which is whatsapp+telegram, and that call site is correct.
+
+- [ ] **Step 3: Widen `dispatchFor` to match the reviewer it calls**
+
+The shared type at `app/lib/channel-pty-bridge/public-session-end-review.ts:41` is
+`'eviction' | 'exit'`. The local callback type narrowed it to `'eviction'`, so the documented
+public-exit path at line 422 could not be expressed. The type is the bug; the value is correct.
+
+In `app/lib/webchat/gateway/webchat-gateway.ts:83`, change:
+
+```ts
+  dispatchFor: 'eviction'
+```
+to:
+```ts
+  dispatchFor: 'eviction' | 'exit'
+```
+
+- [ ] **Step 4: Fix the `port` type**
+
+`requirePortEnv` returns a number; the local was declared `string`. It is only interpolated into a
+URL, so runtime is unaffected, but the declaration is a lie.
+
+In `server/routes/admin/sidebar-sessions.ts`, change `let port: string` to:
+
+```ts
+  let port: number
+```
+
+- [ ] **Step 5: Annotate the five implicit-`any` parameters**
+
+These are callback params on arrays whose element type the compiler can already see; they only
+needed writing down. Read each line and give the parameter the element type in scope — do not
+reach for `any`.
+
+- `server/routes/admin/sessions.ts:638` — params `c` and `i`
+- `server/routes/admin/sessions.ts:667` — param `c`
+- `server/routes/admin/sessions.ts:702` — param `c`
+- `server/routes/whatsapp-reader.ts:1144` — param `r`
+
+- [ ] **Step 6: Run the gate**
+
+Run: `npm run typecheck`
+Expected: exit 1, `[check-types] FAIL errors=62 ignored=0`, and no remaining diagnostic in a file
+outside `__tests__`. Every error left in the package is now in a test file.
+
+- [ ] **Step 7: Prove the ChannelIcon fix with a test**
+
+Add to `app/components/__tests__/ChannelIcon.test.tsx`:
+
+```tsx
+  it('renders a webchat row through the badge without throwing', () => {
+    const { container } = render(<SessionChannelBadge channel="webchat" size={14} />)
+    expect(container.querySelector('.channel-icon')).not.toBeNull()
+  })
+```
+
+Import `SessionChannelBadge` alongside `ChannelIcon` on line 4.
+
+Run: `npx vitest run app/components/__tests__/ChannelIcon.test.tsx`
+Expected: PASS.
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add maxy-code/platform/ui/app maxy-code/platform/ui/server
+git commit -m "fix(1829): production type defects — ChannelIcon webchat crash, dispatchFor, port type"
+```
+
+---
+
+### Task 4: Contract drift the tests exposed — clears 3
+
+In both of these the test is right about the wire and the type is wrong. Fix the type.
+
+**Files:**
+- Modify: `platform/ui/app/Sidebar.tsx:49-60`
+- Modify: `platform/ui/server/routes/channel/__tests__/schedule-inject.test.ts:180,186`
+
+- [ ] **Step 1: Add the fields the 503 refusal actually sends**
+
+`server/routes/admin/claude-sessions.ts:115` returns
+`{ error: 'claude-auth-dead', auth_status: auth.status, expiresAt: auth.expiresAt ?? null }`.
+`RcSpawnResponseBody` declares neither `auth_status` nor `expiresAt`, so
+`resolveRcSpawnOutcome.test.ts:69` — which passes the real body — does not typecheck.
+
+In `app/Sidebar.tsx`, add to `RcSpawnResponseBody` before the closing brace:
+
+```ts
+  /** Task 1407 — the 503 claude-auth-dead refusal (refuseIfClaudeAuthDead,
+   *  server/routes/admin/claude-sessions.ts) carries the token's health and
+   *  expiry alongside `error`. Both were on the wire and absent from this type,
+   *  so a caller reading them had no compiler help. */
+  auth_status?: string
+  expiresAt?: string | null
+```
+
+- [ ] **Step 2: Make the no-seat assertions non-vacuous**
+
+`schedule-inject.test.ts:180,186` assert `.scheduledSessionId` is undefined on the inbound. No
+inbound type declares that property and no source file mentions it, so the assertion is true by
+construction and would stay true if the route started threading a seat under any other name. It
+tests nothing.
+
+The intent (Task 1746: no per-firing seat is threaded) is worth keeping. Express it against the
+object so it stays meaningful if the field is ever added.
+
+Change line 180 to:
+
+```ts
+    expect('scheduledSessionId' in (waHandleInbound.mock.calls[0][0] as object)).toBe(false)
+```
+
+and line 186 to:
+
+```ts
+    expect('scheduledSessionId' in (tgHandleInbound.mock.calls[0][0] as object)).toBe(false)
+```
+
+- [ ] **Step 3: Run the gate and the touched tests**
+
+Run:
+```bash
+npm run typecheck
+npx vitest run app/__tests__/resolveRcSpawnOutcome.test.ts server/routes/channel/__tests__/schedule-inject.test.ts
+```
+Expected: gate reports `errors=59`; both test files pass.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add maxy-code/platform/ui/app/Sidebar.tsx maxy-code/platform/ui/server/routes/channel/__tests__/schedule-inject.test.ts
+git commit -m "fix(1829): type the auth-refusal wire fields, de-vacuum the no-seat assertions"
+```
+
+---
+
+### Task 5: Type the mock implementations — clears 39
+
+One root cause produces most of the remaining errors: `vi.fn()` given an implementation that
+declares no parameters. The mock's type becomes `Mock<() => R>`, so `.mock.calls[0]` is the empty
+tuple `[]` (`TS2493` on any index, `TS2339` on any property of the resulting `never`), and any
+callback over `.mock.calls` gets an implicit-`any` parameter (`TS7006`). Casting the resulting
+`undefined` is `TS2352`.
+
+The fix is the same everywhere: declare the parameters the caller actually passes. That is
+truthful — the production call site already passes them — and it makes every downstream index and
+callback infer correctly.
+
+**Files:**
+- Modify: `app/components/__tests__/SessionReseatControl.test.tsx` (5)
+- Modify: `app/lib/__tests__/graph-write-gate.test.ts` (8)
+- Modify: `app/components/__tests__/UsageModal.test.tsx` (2)
+- Modify: `app/tasks/__tests__/tasks-page.test.tsx` (4)
+- Modify: `app/whatsapp/__tests__/ReplyComposer.test.tsx` (2)
+- Modify: `app/__tests__/AdminShell-operator-conversations.test.tsx` (2)
+- Modify: `app/lib/__tests__/adminuser-self-heal.test.ts` (4)
+- Modify: `app/lib/__tests__/graph-health-audits.test.ts` (3)
+- Modify: `app/lib/whatsapp/__tests__/baileys-debug-window.test.ts` (3)
+- Modify: `server/routes/admin/__tests__/browser-launch.test.ts` (6)
+
+- [ ] **Step 1: Type the fetch-shaped mocks**
+
+Wherever a mock stands in for `adminFetch` or `fetch` and the test later reads `mock.calls[0][1]`,
+declare both parameters. In `app/components/__tests__/SessionReseatControl.test.tsx:30`, change:
+
+```tsx
+    const adminFetch = vi.fn(async () => new Response(JSON.stringify({ target: '/chat?session=new' }), { status: 200 }))
+```
+to:
+```tsx
+    const adminFetch = vi.fn(async (_url: string, _init?: RequestInit) =>
+      new Response(JSON.stringify({ target: '/chat?session=new' }), { status: 200 }))
+```
+
+This clears the three `TS2493` and two `TS2339` in that file, and the `init!` non-null assertion on
+line 45 becomes correct rather than accidental. Apply the same shape to the identical mocks in
+`UsageModal.test.tsx`, `tasks-page.test.tsx` and `ReplyComposer.test.tsx`, matching each call site's
+real argument list — `tasks-page` and `ReplyComposer` currently infer `[url: string]`, so they need
+the second parameter added.
+
+- [ ] **Step 2: Type the console-spy mocks**
+
+Wherever a test reads `logSpy.mock.calls.map((c) => String(c[0]))`, the spy's parameters are
+unstated. Declare them so `c` infers. In `app/lib/__tests__/graph-write-gate.test.ts`, the spy
+should be created as:
+
+```ts
+  const logSpy = vi.spyOn(console, 'error').mockImplementation((..._args: unknown[]) => {})
+```
+
+The six `TS7006` in that file then resolve without touching the assertions. Apply the same to
+`graph-health-audits.test.ts`, `baileys-debug-window.test.ts`, `browser-launch.test.ts`,
+`adminuser-self-heal.test.ts` and `AdminShell-operator-conversations.test.tsx`.
+
+- [ ] **Step 3: Type the Neo4j session mock**
+
+`graph-write-gate.test.ts:201` destructures `session.run.mock.calls[0]`. Give `makeSession`'s `run`
+its real parameters:
+
+```ts
+    run: vi.fn(async (_cypher: string, _params?: Record<string, unknown>) => ({ records: [] as unknown[] })),
+```
+
+- [ ] **Step 4: Run the gate**
+
+Run: `npm run typecheck`
+Expected: exit 1, `[check-types] FAIL errors=20 ignored=0`.
+
+- [ ] **Step 5: Run every touched test file**
+
+Run:
+```bash
+npx vitest run app/components/__tests__/SessionReseatControl.test.tsx app/lib/__tests__/graph-write-gate.test.ts \
+  app/components/__tests__/UsageModal.test.tsx app/tasks/__tests__/tasks-page.test.tsx \
+  app/whatsapp/__tests__/ReplyComposer.test.tsx app/__tests__/AdminShell-operator-conversations.test.tsx \
+  app/lib/__tests__/adminuser-self-heal.test.ts app/lib/__tests__/graph-health-audits.test.ts \
+  app/lib/whatsapp/__tests__/baileys-debug-window.test.ts server/routes/admin/__tests__/browser-launch.test.ts
+```
+Expected: all pass. A mock that now declares parameters must still receive the same arguments — if
+an assertion breaks, the mock's declared shape is wrong, not the assertion.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add maxy-code/platform/ui/app maxy-code/platform/ui/server
+git commit -m "test(1829): declare mock parameters so call-tuple reads typecheck"
+```
+
+---
+
+### Task 6: Stale fixtures and handler types — clears 20
+
+These are not one root cause. Each is a fixture or handler that drifted from the type it stands in
+for.
+
+**Files:**
+- Modify: `app/components/__tests__/session-list-lite.test.tsx` (8)
+- Modify: `app/lib/channel-pty-bridge/__tests__/follower.test.ts` (8)
+- Modify: `app/lib/whatsapp/gateway/__tests__/wa-gateway-source.test.ts` (3)
+- Modify: `app/lib/__tests__/power-health.test.ts` (1)
+
+- [ ] **Step 1: Add the two props the session-list fixture lost**
+
+All eight `TS2739` are the same fixture missing `newPermMode` and `setNewPermMode`, which the
+component gained and the fixture never followed. Find the shared props object in
+`session-list-lite.test.tsx` and add both, matching the types the component declares. If the
+fixture is repeated inline at each of lines 28, 35, 43, 50, 67, 73, 80 and 86, hoist it to one
+`const baseProps` first and spread it — eight copies of one fixture is why this drifted.
+
+- [ ] **Step 2: Fix the follower handler types**
+
+Six `TS2322` at lines 216, 254, 273 and 299 are `Type 'number' is not assignable to type
+'void | Promise<void>'` — a handler written as a concise arrow returning a number
+(`() => someCounter++`). Wrap the body in braces so it returns void.
+
+The four at lines 218, 256, 301 and 354 are `RecordingHandler` not assignable to
+`FileDeliveryHandler`. Read both types before changing anything: if `RecordingHandler` is the
+test's own recording double, give it the `FileDeliveryHandler` signature rather than casting it.
+
+- [ ] **Step 3: Fix the wa-gateway-source mock**
+
+Lines 53 and 54 cast `EnsureChannelSessionInput` to `Record<string, unknown>`, which the compiler
+rejects as non-overlapping. Line 98 assigns a `Mock<(i: Record<string, unknown>) => Promise<void>>`
+where an `EnsureTelegramSession…` signature is required. Type the mock with the real input type
+instead of `Record<string, unknown>`, which removes all three.
+
+- [ ] **Step 4: Fix the power-health runner fixture**
+
+Line 118 adds a `status` key to an object literal typed
+`{ runner: (c: string, a: string[]) => string | null }`. Read what the test intends: if `status` is
+genuinely part of the fixture's contract, add it to the type; if it is a leftover, remove it.
+
+- [ ] **Step 5: Run the gate**
+
+Run: `npm run typecheck`
+Expected: exit 0, `[check-types] ok errors=0 ignored=0 tsc-status=0`.
+
+This is the first green run. If it is not zero, the remaining diagnostics are listed by the gate —
+do not proceed to Task 7 until it is.
+
+- [ ] **Step 6: Run every touched test file**
+
+Run:
+```bash
+npx vitest run app/components/__tests__/session-list-lite.test.tsx \
+  app/lib/channel-pty-bridge/__tests__/follower.test.ts \
+  app/lib/whatsapp/gateway/__tests__/wa-gateway-source.test.ts app/lib/__tests__/power-health.test.ts
+```
+Expected: all pass.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add maxy-code/platform/ui/app
+git commit -m "test(1829): refresh stale fixtures and handler signatures"
+```
+
+---
+
+### Task 7: Prove the gate catches a real error — the mutation check
+
+A gate that has only ever been seen passing has not been shown to work. The load-bearing case is an
+error in a file the narrow 1825 gate never covered.
+
+- [ ] **Step 1: Introduce a deliberate error outside the old gate's six files**
+
+`app/lib/file-index.ts` is not in `CONTRACT_FILES`. Add an implicit-`any` parameter to it — pick any
+callback and strip its annotation, or append:
+
+```ts
+export function __gateProbe(rows) {
+  return rows.length
+}
+```
+
+- [ ] **Step 2: Observe the gate fail on it**
+
+Run: `npm run typecheck; echo "exit=$?"`
+Expected: exit 1, `[check-types] FAIL errors=1 ignored=0`, and the listed diagnostic names
+`app/lib/file-index.ts` with `TS7006`.
+
+- [ ] **Step 3: Confirm the OLD gate would have missed it**
+
+Run: `node scripts/check-loop-contract-types.mjs; echo "exit=$?"`
+Expected: exit 0, `[loop-contract] ok … package-errors-ignored=1`. This is the whole reason the task
+exists — record the output in the debrief.
+
+- [ ] **Step 4: Remove the error and observe the gate pass**
+
+Delete the probe, then run: `npm run typecheck; echo "exit=$?"`
+Expected: exit 0, `[check-types] ok errors=0 ignored=0`.
+
+- [ ] **Step 5: Confirm the gate does not pass blind**
+
+Point it at a tree where tsc cannot run:
+
+```bash
+mv tsconfig.json tsconfig.json.bak && npm run typecheck; echo "exit=$?"
+mv tsconfig.json.bak tsconfig.json
+```
+Expected: exit 1, and the message is `tsc-configuration-failed` or `tsc-produced-no-diagnostics` —
+not `ok`. Record which branch fired.
+
+- [ ] **Step 6: Commit nothing**
+
+This task changes no tracked file. Confirm with `git status --porcelain` that the tree is clean
+before moving on. If the probe or the tsconfig rename is still on disk, undo it now.
+
+---
+
+### Task 8: Retire the narrow gate and wire the wide one
+
+**Files:**
+- Delete: `platform/ui/scripts/check-loop-contract-types.mjs`
+- Modify: `platform/ui/package.json` (`prebuild`)
+
+- [ ] **Step 1: Swap the prebuild gate**
+
+In `platform/ui/package.json`, in the `prebuild` chain, change the final entry from:
+
+```
+&& node scripts/check-loop-contract-types.mjs
+```
+to:
+```
+&& node scripts/check-types.mjs
+```
+
+- [ ] **Step 2: Delete the narrow gate**
+
+```bash
+git rm maxy-code/platform/ui/scripts/check-loop-contract-types.mjs
+```
+
+The loop-row contract is not lost. `check-types.mjs` compiles all six of its `CONTRACT_FILES` along
+with the rest of the package, so every invariant 1825 asserted is still a build failure — now
+without a second gate that could drift from the first.
+
+- [ ] **Step 3: Verify no reference to the deleted gate survives**
+
+Run: `/usr/bin/grep -rn "check-loop-contract-types" maxy-code/ --exclude-dir=node_modules`
+Expected: hits only in `.tasks/` and `platform/docs/superpowers/` prose. Zero hits in
+`package.json` or any script.
+
+- [ ] **Step 4: Run the full build**
+
+Run: `cd maxy-code/platform/ui && npm run build`
+Expected: all nineteen prebuild gates pass, `[check-types] ok errors=0 ignored=0` among them, then
+vite and tsup complete and `postbuild` passes.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add maxy-code/platform/ui/package.json
+git commit -m "feat(1829): wire the package-wide gate into prebuild, retire the narrow one"
+```
+
+---
+
+### Task 9: Run the package's own test suite
+
+The plan changed twenty test files and one dependency major version. The gate proves types; only the
+suite proves behaviour.
+
+- [ ] **Step 1: Run the full suite**
+
+Run: `cd maxy-code/platform/ui && npx vitest run`
+Expected: exit 0.
+
+Do not dismiss a failure here as a worktree artefact. As of 2026-07 the worktree suite is
+trustworthy — verify any failure against the parent checkout on `main` before calling it
+environmental, and if it is real, fix it before landing.
+
+- [ ] **Step 2: Record the count**
+
+Note the file and test totals for the debrief.
+
+---
+
+### Task 10: File the follow-up for the rest of the platform
+
+`platform/lib/*` and `platform/plugins/*` still typecheck nowhere. The task scopes them out, and a
+prose deferral becomes a silent regression.
+
+- [ ] **Step 1: Mint a task number**
+
+Scan the worktrees, not just `main` — parallel sprints take numbers concurrently:
+
+```bash
+ls /Users/neo/getmaxy/maxy-code/.tasks/*/ /Users/neo/getmaxy/maxy-code/.claude/worktrees/*/maxy-code/.tasks/*/ 2>/dev/null \
+  | /usr/bin/grep -oE '^1[89][0-9]{2}' | sort -n | tail -3
+```
+
+- [ ] **Step 2: Write the task file**
+
+Create `maxy-code/.tasks/backlog/<NNNN>-<slug>.md` describing: the other platform packages run no
+typechecker; `platform/ui` now has `scripts/check-types.mjs` as the working shape to copy; each
+package has its own error population that needs the same triage-then-gate treatment; and that the
+`neo4j-driver` v5/v6 split is now uniform at v5 so a future v6 move is a single coordinated bump.
+Task files nest to `##`, never `###`.
+
+- [ ] **Step 3: Add a Ready row to LANES**
+
+Edit `/Users/neo/getmaxy/maxy-code/.tasks/LANES.md` — use the absolute path, since a bare
+`.tasks/LANES.md` from the worktree root resolves to the legacy parent tracker.
+
+- [ ] **Step 4: Commit**
+
+Fold this into the Task 1829 archive commit in the sprint's land phase rather than committing it
+alone.