@rubytech/create-sitedesk-code 0.1.524 → 0.1.525

package/payload/platform/docs/superpowers/specs/2026-07-24-task-1942-subaccount-switcher-brand-head-design.md

@@ -1,35 +0,0 @@
-# Task 1942 — Sub-account switcher moves to the sidebar brand head
-
-Design doc. Source task: `.tasks/1942-subaccount-switcher-moves-to-sidebar-brand-head.md`.
-
-## Goal
-
-Open the sub-account picker by clicking the account name at the top of the sidebar, not from the footer kebab. Remove the switcher from the footer menu.
-
-## Resolved decisions (brainstorm)
-
-1. **Click target:** the whole brand head (`side-brand`: icon + two-line lockup) becomes one button when the switcher is available.
-2. **Affordance:** a small down-chevron renders after the business name to signal the dropdown.
-3. **Close:** re-clicking the head toggles it shut, and a transparent full-screen scrim behind the panel closes it on any outside click. Mirrors the footer-menu scrim it replaces.
-
-## Availability gate (unchanged from today)
-
-Switcher is available only when `subAccounts.length > 1 && Boolean(onSwitchAccount)`. Unavailable → the head stays a plain non-interactive `<div>`, no chevron, no picker. This is the current `switcherAvailable` gate, moved from `AccountMenu` to `Sidebar`.
-
-## Components and flow
-
-- **`Sidebar.tsx`** owns `switcherOpen` state. The brand head renders as `<button aria-haspopup="menu" aria-expanded={switcherOpen}>` when available, else the current `<div>`. Click toggles `switcherOpen`; the closed→open transition fires `refreshAccounts?.()` and emits `[admin-ui] op=subaccount-switcher-toggle anchor=brand-head open=<bool> available=<bool> accounts=<N>`. `SubAccountPicker` renders inside `.side-brand`, anchored beneath it, with a sibling scrim that closes on click.
-- **`AccountMenu.tsx`** loses the `switcherAvailable`/`switcherOpen` block, the `SubAccountPicker` import, and the five switcher props. `UserRound` import dropped if otherwise unused.
-- **`globals.css`** gives `.side-brand` `position: relative` and re-anchors `.sub-account-picker-panel` left-aligned under the head (drop the retired header-title `translateX(-50%)` centering). Adds `.side-brand` button-reset styling (transparent, inherit, pointer) and the chevron. Deletes the dead `.side-foot-menu .sub-account-picker-panel` / `-list` overrides.
-
-## Collapsed rail (edge, in scope to not break)
-
-When `sidebar-collapsed`, existing CSS hides `.side-brand-lockup` (name + chevron), leaving only the icon. The head-button still functions on the icon, but no new collapsed affordance is added (per task out-of-scope). The picker anchors under `.side-brand` in both states.
-
-## Testing
-
-vitest + jsdom (Node 22). New `Sidebar` test: available → head is a button, click mounts the picker and fires `refreshAccounts`, re-click closes; unavailable → not a button, no picker. `AccountMenu.test.tsx`: no "Switch account", switcher props dropped. `SubAccountPicker.test.tsx` unchanged.
-
-## Out of scope
-
-`SubAccountPicker` internals, the switch mechanism, other `AccountMenu` items, a dedicated collapsed-rail affordance, maxy-lite, Task 1940's mobile lite tab bar.

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

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

package/payload/platform/docs/superpowers/specs/2026-07-26-task-1926-portal-push-concurrency-guard-design.md

@@ -1,200 +0,0 @@
-# Task 1926 — same-account portal push concurrency guard (design)
-
-**Date:** 2026-07-26
-**Task:** [`.tasks/1926-concurrent-same-account-portal-push-lets-the-pre-stage-clear-delete-the-live-tree.md`](../../../../.tasks/1926-concurrent-same-account-portal-push-lets-the-pre-stage-clear-delete-the-live-tree.md)
-**Touches:** `platform/plugins/cloudflare/bin/portal-index-push.mjs`, `platform/plugins/cloudflare/mcp/__tests__/portal-index-push.test.ts`
-
-## Problem
-
-`pushAccount` stages an account's file index at `next = currentGeneration + 1`, flips
-the `directory_state` pointer to `next`, then sweeps every other generation. Task 1923
-added a pre-stage `DELETE FROM directory WHERE accountId = ? AND generation = ?` bound
-to `next`, so a stage that died mid-batch could self-heal instead of colliding forever
-on `UNIQUE (accountId, relPath, generation)`.
-
-Two pushes of one account break that. The second writer reads `current = 5` before the
-first writer's flip, computes `next = 6`, and by the time its pre-stage DELETE runs the
-pointer already names generation 6. The DELETE removes the live tree. A client listing
-in the gap between that DELETE and the re-insert sees an empty portal.
-
-The overlap is reachable: the admin server's 60s loop calls `pushAllAccounts`, and a
-hand-run `node portal-index-push.mjs --account <id>` calls the same `pushAccount` from a
-separate OS process.
-
-## What success looks like
-
-Two concurrent pushes of one account never leave a reader seeing an empty or partial
-tree, and never delete rows at the pointer's generation.
-
-## Why the three candidate approaches in the task file were rejected
-
-**A per-account advisory lock.** The two racers are separate OS processes. A JavaScript
-mutex inside the admin server does not exist in the CLI process, so it guards nothing.
-A lock that does work across processes has to live in D1, which means new columns, a
-lease, and a lease expiry. A lease expiry reintroduces the wedge class Task 1923 just
-removed: a holder that dies wedges the account until the lease runs out, and a push
-slower than its lease keeps writing after another writer has taken over.
-
-**`next` from `MAX(generation)` alone.** This stops two writers sharing a staging
-generation, but the slower writer still flips the pointer down onto its own generation
-after the faster writer has already swept it. The reader still sees an empty tree, so
-the success criterion is not met.
-
-**Scoping the clear to `generation = next AND generation != current`.** `current` is a
-value read at the top of the push. By the time the DELETE runs, the pointer has moved.
-Re-reading the pointer immediately before the DELETE narrows the window without closing
-it, because the peer can flip between the re-read and the DELETE.
-
-## Design
-
-Three changes to `pushAccount`. No lock, no lease, no schema change, no new table.
-
-### 1. Claim a generation above everything that exists
-
-Keep the existing pointer read, and add one statement beside it:
-
-```sql
-SELECT MAX(generation) AS g FROM directory WHERE accountId = ?
-```
-
-`next = Math.max(current, maxStagedGeneration) + 1`.
-
-A peer that has already inserted at least one row is visible in that MAX, so the two
-writers claim different generations and neither stages into the other's rows.
-
-Two statements rather than one nested `UNION ALL`: each is trivially readable, each is
-trivially fakeable in a test, and the pointer read stays the push's first statement,
-which an existing test asserts.
-
-### 2. The flip only ever moves the pointer forward
-
-```sql
-INSERT INTO directory_state (accountId, currentGeneration) VALUES (?, ?)
-ON CONFLICT (accountId) DO UPDATE SET currentGeneration = excluded.currentGeneration
-WHERE excluded.currentGeneration > directory_state.currentGeneration
-```
-
-SQLite has supported a `WHERE` clause on upsert's `DO UPDATE` since 3.24, and D1 is
-SQLite. This is what makes a losing writer harmless: it cannot drag readers back onto a
-generation the winner has already swept.
-
-The D1 client returns rows, not affected-row meta, so the flip is followed by a pointer
-readback. That readback is the branch point:
-
-- **Pointer equals `next`.** We won. Log `op=flip`, sweep, verify, return. Unchanged
-  behaviour.
-- **Pointer is above `next`.** A peer won. Log
-  `op=stage-contended account=<id> generation=<next> pointer=<actual> action=superseded`
-  and return without sweeping and without verifying. Both of those would measure the
-  peer's tree against our expected row count, and `op=verify` would read as a failure
-  when nothing failed.
-
-Our staged rows at the losing generation are left in place. They are invisible (no
-reader sees a generation the pointer does not name) and the winner's next sweep collects
-them.
-
-### 3. The sweep only ever removes older generations
-
-```sql
-DELETE FROM directory WHERE accountId = ? AND generation < ?
-```
-
-`< next` rather than `!= next`, so a writer never deletes a peer's higher in-flight
-stage. Rows above `next` from an abandoned stage still converge: the following cycle
-claims a generation above them and sweeps them once it flips.
-
-### 4. The Task 1923 pre-stage clear is removed
-
-Because `next` is now always above every existing generation for the account, the orphan
-`SELECT COUNT(*) ... generation = next` can only ever return 0 and the pre-stage DELETE
-can never match a row. Leaving unreachable code whose comment claims it is the wedge
-heal would be false narration, so the orphan count, the DELETE, the `op=stage-clear` log
-line and its two tests go.
-
-Task 1923's outcome is preserved by construction and is stronger than before. A stage
-that died mid-batch leaves rows at generation 6; the next run claims 7, so there is no
-UNIQUE collision to freeze on, and the gen-6 orphans are swept after the flip. The heal
-now happens with no DELETE before the flip at all, which is exactly what removes this
-task's hazard rather than narrowing it.
-
-This was confirmed with the operator before the spec was written, because Task 1926
-lists Task 1923's heal as out of scope.
-
-## Cases covered, and the one left fail-closed
-
-**Peer reads the generation after we have staged a row.** It claims a higher generation.
-Both pushes complete. The forward-only flip picks the winner. The reader sees the old
-complete tree, then one complete new tree. Neither push fails.
-
-**Both read the generation before either inserts.** Both claim the same generation. The
-second writer's first INSERT hits `UNIQUE (accountId, relPath, generation)` and that push
-throws. Both walks resolve the same exposed set and `walkExposed` emits the exposed dirs
-in the same order, so the second writer collides on its first row and contributes
-nothing. The reader is safe: the winner's tree is complete and the pointer never moved
-backward. The loser logs `op=failed` and the next 60s cycle succeeds.
-
-This second case is left fail-closed rather than retried. The task's success criterion is
-about what a reader can see, and a loud failure that self-corrects one cycle later meets
-it. A retry-on-collision path would be an invented requirement.
-
-**The one residual, stated rather than fixed.** The claim above relies on both walks
-starting with the same row. If the account's `SCHEMA.md` or `data-portal.json` changes in
-the window between the two generation reads, the two walks can begin with different rows,
-so the second writer contributes some non-overlapping rows at the shared generation before
-colliding on a shared one. The winner then flips onto its own complete tree plus those few
-extra rows. That is not an empty tree and not a partial one, so it does not breach the
-success criterion, and the next cycle's sweep removes the whole generation. No task file is
-filed for it because nothing is deferred: the case is inside what this design covers, and
-its outcome is a stale row for one cycle rather than a reader-visible break.
-
-## Observability
-
-`op=stage-contended account=<id> generation=<next> pointer=<actual> action=superseded`
-is emitted when a push's flip was superseded by a peer. This deviates from the task
-file's `action=<waited|skipped>` wording: the design never waits and never skips work, so
-neither value describes what happened. `superseded` names the actual outcome, and
-`pointer=` names the generation that won, which is what an operator needs to correlate
-the two runs.
-
-`op=stage-clear` is retired with the code that emitted it. The task file's line that a
-`stage-clear` with `cleared=` equal to the live tree size must never appear is satisfied
-absolutely: no `stage-clear` line can appear at all.
-
-## Testing
-
-Both new tests drive two interleaved `pushAccount` calls against one shared fake store
-and snapshot the reader's view after every statement. The assertion is the success
-criterion stated directly: the visible tree is never empty and never a strict subset of
-a complete tree.
-
-1. **The task file's interleave.** Writer B reads the generation, then pauses. Writer A
-   runs to completion. B resumes. Red on current code, because B's pre-stage DELETE binds
-   the generation the pointer now names and the snapshot goes empty. Green after, because
-   B collides on UNIQUE and A's tree is untouched. This test also asserts that no DELETE
-   is ever issued naming the pointer's current generation, which is the other half of the
-   success criterion.
-
-2. **The higher-claim interleave.** Writer A stages fully but pauses before its flip.
-   Writer B reads the generation, sees A's staged rows in the MAX, claims the next one up,
-   and completes. A resumes and its flip is a no-op. Asserts the pointer never moves
-   backward, that A emits `op=stage-contended` with `action=superseded`, and that A
-   issues no sweep.
-
-The existing 27 tests stay green apart from the two Task 1923 stage-clear tests, which
-are removed with the code they cover.
-
-## Scope boundaries
-
-**In scope:** the generation claim, the forward-only flip, the backward-only sweep, the
-removal of the pre-stage clear, and the two-writer regression tests.
-
-**Out of scope:** INSERT batching (Task 1842). Cross-account contention (separate
-generation counters, no contention). Any change to `runTargets`, `recordSuccess`, or the
-portal reader in `files.ts`.
-
-## Deployment
-
-`portal-index-push.mjs` ships inside the installer payload and is inlined into the admin
-server bundle. No D1 migration is required: every statement runs against the existing
-`directory` and `directory_state` tables as defined in
-`platform/plugins/cloudflare/skills/data-portal/schema.sql`.

package/payload/platform/docs/superpowers/specs/2026-07-26-task-2014-ui-suite-nondeterminism-design.md

@@ -1,169 +0,0 @@
-# Task 2014 design — cut the jsdom the `platform/ui` suite does not use
-
-Date: 2026-07-26
-Task: `.tasks/pending/2014-platform-ui-suite-is-nondeterministic-under-parallel-load.md`
-Supersedes brief: 1765, folded into 2014 on 2026-07-26
-
-## The measurement this design rests on
-
-All figures from the dev Mac, Node 22.22.0, vitest 4.1.2, worktree
-`task-2014-ui-suite-nondeterminism`, 2026-07-26.
-
-### Most apparent worktree flakiness is missing build output, not flakiness
-
-`platform/node_modules` and `platform/lib/*/dist` are gitignored build output. A
-fresh worktree has neither. Four full-suite runs, each after adding one more
-piece of provisioning:
-
-| Run | Worktree state | Failed | Duration |
-|---|---|---|---|
-| 1 | `platform/ui` deps only | 63 files / 32 tests | 435s |
-| 2 | + 3 libs built | 5 files / 8 tests | 180s |
-| 3 | + `platform` deps | 5 files / 3 tests | 111s |
-| 4 | + all 24 libs built | 0 | 143s |
-
-Runs 1 and 2 failed on `Cannot find module .../dist/index.js` and
-`Failed to resolve import "neo4j-driver"`. Those are absent artifacts, not
-timing. Only run 3's three failures are the defect this task describes, and all
-three are in the brief's population: both `/login/start` sub-account cases in
-`whatsapp-self-or-house-scope.test.ts` at 5013ms and 515ms, and
-`whatsapp-conversation-graph-state-projection.test.ts` "sub-account all-senders
-mode returns only its bound thread" at 5017ms. 5000ms is the vitest default
-`testTimeout`.
-
-### Environment setup costs six times what the tests cost
-
-Run 4, fully green:
-
-```
-tests        267s
-environment 1571s
-import       257s
-setup        196s
-transform     42s
-```
-
-`vitest.config.ts` sets `environment: 'jsdom'` globally. 530 test files pay it.
-
-### Roughly half the suite boots a DOM it never touches
-
-266 `.test.ts` files do not declare `@vitest-environment node`. Both runs
-back to back, same machine load:
-
-| | Duration | environment CPU |
-|---|---|---|
-| as-is (jsdom) | 103.0s | 1317.6s |
-| `--environment node` | 30.9s | 0.074s |
-
-Three consecutive node-environment passes over those 266 files agreed on 17
-`.ts` files that genuinely need a DOM. A file that appeared in only one pass
-(`route-cache-watchers.test.ts`) is the known flake, not a DOM dependency. A
-`.tsx` file in the failure list arrived because vitest CLI arguments are
-substring filters rather than exact paths.
-
-So the suite's problem is not 4757 tests. The tests are 267s of CPU. It is that
-about half the files run a browser DOM environment for nothing, and that is the
-CPU starving the workers the named tests race against.
-
-### Machine context
-
-The dev Mac ran these measurements at load average 100 to 350 with 60 `claude`
-processes across six peer worktree sessions. Self-contention from 20 vitest
-forks is not the only contender for CPU, and any verification has to record the
-load it ran under or a red run cannot be attributed.
-
-## Design
-
-### 1. Route the test environment by file extension
-
-`platform/ui/vitest.config.ts` replaces its single global `environment: 'jsdom'`
-with two projects:
-
-- `dom`: `**/*.{test,spec}.?(c|m)[jt]sx`, environment `jsdom`.
-- `node`: `**/*.{test,spec}.?(c|m)[jt]s` plus `../scripts/__tests__/**`,
-  environment `node`.
-
-The existing `resolve.dedupe`, `setupFiles`, `globals`, and `exclude` settings
-carry into both projects unchanged.
-
-The rule is structural, not a maintained list: a test that renders JSX gets a
-DOM, and anything else opts in explicitly. No `.tsx` file is edited.
-
-### 2. Seventeen `.ts` files opt back into jsdom
-
-Each gets `// @vitest-environment jsdom` with a short reason. Verified on vitest
-4.1.2 that a per-file docblock overrides a project's `environment` setting.
-
-```
-app/__tests__/spinning-class-global.test.ts
-app/__tests__/wa-viewer-width.test.ts
-app/graph/__tests__/side-panel-helpers.test.ts
-app/hooks/__tests__/useCopyFeedback.test.ts
-app/hooks/__tests__/useMediaQuery.test.ts
-app/hooks/__tests__/useVoiceRecorder.deviceId.test.ts
-app/hooks/__tests__/useVoiceRecorder.mic-result.test.ts
-app/lib/__tests__/admin-auth-login-remote-auth.test.ts
-app/lib/__tests__/switch-account-scope.test.ts
-app/lib/__tests__/use-admin-auth-claude-connected.test.ts
-app/lib/__tests__/use-admin-auth-heartbeat-remote-auth.test.ts
-app/lib/__tests__/useAdminFetch.test.ts
-app/lib/__tests__/useSubAccountSwitcher.test.ts
-app/public/__tests__/extract-seed-question.test.ts
-app/whatsapp/__tests__/useTranscriptStream-activity.test.ts
-app/whatsapp/__tests__/useTranscriptStream-endpoint.test.ts
-app/whatsapp/__tests__/useTranscriptStream.test.ts
-```
-
-A `.ts` test that needs a DOM and lacks the docblock fails loudly on
-`document is not defined`. It does not pass silently.
-
-### 3. A prebuild gate so the waste cannot creep back
-
-New `platform/ui/scripts/check-jsdom-budget.mjs`, joining the 24 checks already
-in the `prebuild` script. It counts the files that will boot jsdom, which is
-every `.test.tsx`/`.spec.tsx` plus every `.ts` test declaring the jsdom
-docblock, and fails the build when that count exceeds a ceiling written in the
-script. Adding a jsdom file becomes a deliberate one-line bump with a reason,
-not an accident. The failure message names the files above the ceiling and the
-CPU cost per jsdom file measured here, so a reader knows what the number buys.
-
-### 4. The 141 existing `@vitest-environment node` docblocks stay
-
-They remain accurate and are now redundant. Removing them is 141 files of churn
-for no behaviour change.
-
-## What this does not claim
-
-Removing the environment waste reduces the contention the named tests race
-against. It is not proven, before measurement, that the ten named tests stop
-failing. If group A's long-press tests still race React Testing Library's
-1000ms `findBy` default once contention drops, that is a second and separate
-lever, and it gets measured and brought back rather than stacked on top as a
-speculative second fix.
-
-## Verification
-
-**Group A and the suite.** Ten consecutive `npm test` runs in `platform/ui` on
-the merged branch, `uptime` captured before and after each run, exit code and
-any `×` lines collected to one file. Success is ten `exit=0` and zero `×`
-matches across the collection, reported alongside the load each ran under. A red
-run with its load recorded is attributable; a red run without is not.
-
-**Group B.** Ten runs do not test a one-in-twenty failure rate. Instead measure
-the wall-clock cost of the four group B seed calls under full-suite parallel
-load, before and after the change, and state the headroom inside the 5000ms
-default. The measurement is the evidence, not the run count.
-
-**The jsdom cut itself.** The suite must still report 530 files and 4757 tests.
-A file silently dropping out of the run because a glob missed it would look like
-a pass.
-
-## Out of scope
-
-- The `platform/lib` build artifacts that made runs 1 to 3 look flaky. That is
-  worktree provisioning friction and gets its own task file.
-- A blanket `testTimeout` bump, excluded by the brief.
-- Deleting, skipping, or loosening the four group B tests, excluded by the
-  brief: they are the only place the cross-account 403 ordering is asserted.
-- Removing the 141 redundant node docblocks.
-- Any product change to the whatsapp routes, the data browser, or graph-write.