# Workspaces & Panels — working TODO Living list. Add items as they are found, tick them as they land, and write the resolution _into_ the item rather than deleting it — the reason a thing was done is worth more later than a clean list. Move anything fully settled to §7. **How the framework actually works is documented separately, in `workspace-panels.md`** — read that first if you are new to it. This file is only the defect list and the work queue. **Why any of it matters is in `agent-coordination.md`** — the north star. **This list stays ordered by defect severity. The re-rank against the objective lives in `agent-coordination.md` §6** _(done 2026-08-07)_, and the two orderings deliberately disagree — read §6 before deciding what to pick up next. Its conclusions in one paragraph: - **Tier A, on the critical path:** the swallowed persist failure (§1), the PATCH dispatcher's missing `else` (§2), validate-on-read + the `'[]'` layout default + an error boundary (§4), the two resize-debounce lost-update items (§5.5), the never-invalidated cache (§5.5), and tests for `layout-utils.ts` (§9). Five of the seven are one defect — _a write that silently did not land_ — and they matter because panel identity now lives in the layout jsonb. **Tier A is empty as of 2026-08-07.** §1's `.catch(() => {})` (`70c2f08`), all of §2 and §3's missing `userId` predicate (`f4ed740`), §9 (`85452d1`), all three Tier A items in §4 — the error boundary (`64961d4`), validate-on-read and the `'[]'` layout default (`ef036df`) — and §5.5's three: the two resize-debounce lost updates (`b0a32ae`) and the never-invalidated cache (`81ad3ef`). Everything the re-rank put on the critical path for "the human opens the dashboard in the morning and sees the result" has landed. **Pick up from Tier B.** - **Tier B:** `dashboardId`-as-a-bag (§5.9) — the agent address book is keyed on it; panel lifecycle (§5.1), but inverted: the requirement is that closing a chat panel must _not_ destroy the agent; `normalizeLayout` as framework (§5.4); and the mobile-collapse decision (§6), which swings on one unanswered question. **§5.9 is closed** (`dbe585f`, `717580f`, `585f234`, `d3922bd`, `ca046a3`) — the bag is a parsed identity, the app-config fields are deleted or moved onto the app, and the inert context is built once. **§5.1's first two items are closed too** (`04371a9`, `198dc71`, `c92b51c`) — panels have a close signal that fires on a real close and on nothing else, and the terminals use it; the chat panel deliberately does not, which is the inversion above. **§5.4's first item is closed** (`1de1d92`) — the allow-list is a `WorkspaceView` prop and the fourteen copies are gone. Tier B is now the pty backstop (the third item of §5.1) and the mobile decision (§6) — **both of which are blocked on a question only the owner can answer**, not on work. §5.4's second item was inventoried and dropped as compression rather than deduplication; see the item for the reasoning and the three defects the inventory turned up instead. **Tier B has no unblocked work left.** - **Tier C, orthogonal:** everything else — including **§5.2 (remounts) and §5.3 (drag-to-move), both large downgrades.** A panel is now a pointer to a server-side session, so a remount costs a replay, and the drag hazard is disarmed by resolving identity by name (`e588524` + `bc82086`). - **And the result that matters: no item in this file blocked building the MVP.** It was built and ran unattended on the framework as it stands. Stop treating this list as the prerequisite queue for the objective. Findings and full reasoning: `COMMS/workspace-panel-framework-analysis-2026-08-07.md`. Every `file:line` below was opened; DB claims were run against live `officer_dev`. Paths are relative to `platform/src/workspaces/officerdev/src/` unless they start with `servers/`, `databases/` or `sidecars/`. **Framework core:** `components/Workspace/` — 12 files, 1,533 lines. No tests exist for any of it. **Two open decisions gate real work — see §6.** Don't start item 4.1 or 5.3 before those are answered. --- ## 1. Observability first — do these before anything else Both are two-line fixes, and without them you cannot tell whether any later fix worked. **Both are done as of 2026-08-07** — they went in with the terminal close wiring (§5.1), which is what they were blocking: there was no way to see whether a shell had actually been killed. §1's third item (the swallowed persist failure) was already closed. **§1 is empty.** - [x] **Fix the Running Shells paths — the panel has 404'd since 2026-07-31.** — done `c92b51c`. `apps/Terminal/RunningShells.tsx:43,49` call `/terminal/sessions` and `DELETE /terminal/sessions/:id`. `useClient` prefixes `/api`; `servers/sidecar/create-proxy.ts:69` strips the mount prefix, so the sidecar receives `/sessions`. The pty sidecar serves only `/_officer/sessions` (`sidecars/pty/server.mjs:30`) and `/_officer/sessions/:id` (`:34`) — everything else 404s at `:40`. Correct paths: `/terminal/_officer/sessions` and `/terminal/_officer/sessions/:id`. The panel (`fccf212`) predates the proxy move (`7129cd8`) that deleted the old `servers/api/terminal/router.ts` and was never updated. Symptom today: permanently reads "No shells running", kill button is a silent no-op. **Confirmed against the running sidecar before fixing**: `GET /sessions` → `{"error":"not found"}`, `GET /_officer/sessions` → the list. Both paths corrected. - [x] **Surface the `clients` count in Running Shells.** — done alongside the paths. `RunningShells.tsx` dropped the `clients` field the sidecar returns (`sidecars/pty/sessions.mjs:169`) — the one field that distinguishes an orphan (`clients: 0`) from a live shell. Now on the type, rendered as "N attached", and `clients === 0` also earns the row an **orphan** badge, since the count is only useful if you do not have to read it to notice. - [x] **Stop swallowing persist failures.** `state/src/useDashboardState.ts:46` is `.catch(() => { })`. Every 500 in this document is invisible because of it — the optimistic cache keeps the UI correct until reload. At minimum log; better, surface a toast and roll the cache back. **Tier A1 — the single highest-value item in this file against the objective** (`agent-coordination.md` §6.2). A panel's `config.agentName` is written through this path, so a swallowed 500 leaves a panel that shows its name, answers to its name, and forgets it on reload: invisible for exactly as long as nobody is looking, which is the window the whole project serves. **Resolved `70c2f08`** — both catches now `console.error` and raise a toast naming the key, and roll the cache back. The rollback is a **compare-and-swap**: it only reverts if the cache still holds exactly what that call wrote. Writes to one key overlap freely (a window resize fires one per group), and a blind rollback over a later successful write would turn one failure into two. **The other three, not through this hook, resolved `81ad3ef`:** the direct `client.patch('/dashboards', …)` calls in `apps/Dashboards/DashboardListApp.tsx:93` and `DashboardPreview.tsx:323,326,356` — dashboard create, rename and delete, which build multi-key patches and so bypass `useDashboardState`. They now call `persistDashboardState`, which shares the hook's in-flight bookkeeping and, on failure, **invalidates rather than reverts**: once the roster has been rewritten and keys dropped from the blob there is no single previous value to swap back, and a refetch is the only thing that makes the list agree with the server. A failed delete used to leave the dashboard gone from the list and alive on the server, reappearing at the next reload with no hint why. --- ## 2. Live data loss **All four resolved in `f4ed740`** — they were one defect with four faces, so they were fixed as one change. Each item keeps its diagnosis below and records what was done. Verified against the live server: an unknown key 400s, the three prefixes round-trip through a GET, a null on a live dashboard is a no-op, and the rename sequence leaves `workspaces` with no zombie. - [x] **The PATCH dispatcher silently drops three key families in active use.** `servers/api/dashboards/dashboards.ts:26-88` is a chain of `if (match) { …; continue; }` that ends with **no `else`** — unmatched keys are dropped and the request returns 200 with a fresh state blob. Matched: `workspaces`, `ws-layout-*`, `ws-terminals-*`, `ws-host-terminals-*`, `screens/*`. `apps/Terminal/CommandTerminalWrapper.tsx:18` writes `ws-${statePrefix}-${dashboardId}`, and the registered prefixes (`apps/Terminal/index.tsx:22,27,34`) are **`tmux`, `nvim`, `claude-code`**. So the panel→session map for those three survives only in the React Query cache, for the life of the tab. **Every reload mints a fresh uuid and abandons the previous pty** — alive, unreachable, never killed. (Tmux's own state survives via `new-session -A -s off-`; the shell running `tmux attach` does not.) Two parts: add the three families, **and** add a fallback `else` that 400s on an unknown key. **Tier A2** — the server half of A1. `ws-layout-*` _is_ matched, so panel `config` persists today (verified: the `agent-mvp` layout round-trips with `config: {agentName: …}` intact). The missing `else` means the next key family added for coordination is a silent no-op returning 200. **Resolved.** The three maps live in a new `dashboards.panel_state` jsonb bag keyed by prefix (`{tmux: {panelId: sessionId}, …}`), with `dashboard_defaults.panel_state` for panels on a screen. A bag rather than three columns because the fourth prefix should not need a schema change; an allow-list rather than a regex because `ws--` cannot be split without one — both halves may contain dashes. `PANEL_STATE_PREFIXES` in `servers/api/dashboards/dashboards.ts` must stay in step with the `statePrefix` props in `apps/Terminal/index.tsx`, and **the new fallback `else` — a 400 naming the key — is what tells you when it does not.** Living on the dashboard row also means the maps are deleted with it. - [x] **`ws-terminals-{id}: null` on a live dashboard is a 500.** Same file, `:61-66` — the `ws-layout-*` branch has a `value === null` → `deleteDashboard` case (`:42`); the terminals branches do not. A null falls to the UPDATE branch and sets a `NOT NULL` column (`databases/officer_db/src/queries/dashboards.ts:70`) → 23502. **Resolved.** A null on either terminals branch is now a no-op: it means "forget this key", and it only ever arrives paired with `ws-layout-{id}: null` on a rename, by which point the row is gone. - [x] **`HostTerminalWrapper` never strips the prefix, so it mints phantom dashboards.** _(found 2026-08-07, latent — `dashboards` is still 0 rows)_ `apps/Terminal/HostTerminalWrapper.tsx:12` is `` `ws-host-terminals-${dashboardId}` `` with **no regex**, while its sibling `TerminalWrapper.tsx:13-14` correctly matches `^ws-layout-(.+)$` first. So the key becomes `ws-host-terminals-ws-layout-` or `ws-host-terminals-screens/terminal`, the dispatcher's `^ws-host-terminals-(.+)$` branch captures that whole string as an id, and `upsertDashboard` **inserts a row when the id is unknown** (`queries/dashboards.ts:75-86`, `name: data.name ?? id`). `getAllDashboardState` maps every `dashboards` row into `workspaces`, so the garbage id surfaces in the Dashboards list as a real dashboard. Two apps deriving a state key from the same string by two different rules is the actual defect; the id-shaped-string-as-a-bag problem behind it is §5.9. Latent only because `officerdev/terminal-host` is in no default layout and hidden from the picker. **Resolved.** All three wrappers now call `terminalStateKey(prefix, dashboardId)` (`apps/Terminal/state-key.ts`) — `TerminalWrapper`'s rule, extracted, with the reasoning beside it. Belt and braces on the server: the terminals and panel-state branches use a new `updateDashboard` that will not INSERT, and **404 on an unknown id instead of creating one**. §5.9 is still the real fix; this closes the hole a mis-derived key could fall through. - [x] **Renaming a dashboard resurrects it as a zombie row.** `apps/Dashboards/DashboardPreview.tsx:316-318` PATCHes `ws-layout-old: null` _and_ `ws-terminals-old: null` together. The first deletes the row; the second then calls `upsertDashboard`, finds nothing, and **re-INSERTs it** with `name = id`. The old slug reappears in `workspaces` on the next GET as a duplicate. Fixed by the item above, but verify this specific sequence after fixing. **Resolved, and verified as the specific sequence:** create `zombie-test`, then PATCH `{ws-layout-renamed: …, ws-layout-zombie-test: null, ws-terminals-zombie-test: null, ws-host-terminals-zombie-test: null}` in one body. `workspaces` comes back as `['agent-mvp', 'renamed']`. --- ## 3. Multi-user correctness — before another member creates a dashboard `dashboards` is **empty (0 rows)** today, so none of this has fired yet. Members can now sign in (`d8ee678`), so it is a matter of time. Note `TODO.md`'s preamble still says the platform is collapsing to single-user — that predates the capability permission model and should not be used to deprioritise these. - [ ] **`dashboards.id` is a global primary key but ids are `slugify(name)`.** `databases/officer_db/src/schema/dashboards.ts` declares `id: text('id').primaryKey()`. Live: `"dashboards_pkey" PRIMARY KEY, btree (id)` plus a redundant `"uq_dashboards_user_id" UNIQUE, btree (user_id, id)` — evidence per-user ids were intended and half-built. Ids come from `DashboardPreview.tsx:300` (`slugify(trimmed) || generateSlug()`) and the uniqueness loop at `:340` checks **only the caller's own dashboards**. Two users both naming a dashboard "Work" → both get `id = 'work'` → the second violates the PK → 500 → swallowed → the dashboard shows, then vanishes on reload. Fix: composite PK `(user_id, id)`, or uuid ids. Composite PKs have a known drizzle re-diff quirk (see `databases/CLAUDE.md` → "Composite keys") — harmless churn, but read the plan. - [x] **`upsertDashboard`'s UPDATE has no `userId` predicate.** `databases/officer_db/src/queries/dashboards.ts:73` — `db.update(dashboards).set(set).where(eq(dashboards.id, id))`. The `existing` lookup above it _is_ scoped, so it cannot reach another user's row today, but it is a non-transactional read-then-write. **It becomes a live cross-user overwrite the moment the PK above is made composite.** Do both in one change or the first fix opens the second. **Resolved `f4ed740`, incidentally.** `upsertDashboard` is now `updateDashboard` (scoped by `(userId, id)`, `RETURNING` to say whether it matched) with an INSERT only when that returns nothing — so the read-then-write is gone as well as the missing predicate. **The composite-PK item above is still open**, and is still the one that matters; this just no longer opens a second hole when it lands. --- ## 4. Resilience — one bad row is currently a white screen _The first three items are Tier A (`agent-coordination.md` §6.2, A3–A4). This is the last mile of the objective: work proceeds overnight, and the human's only act is to open the dashboard and look. A malformed row turning that into a white screen loses the result at the one moment it is consumed — and `config` added a new unvalidated field to an already-unvalidated tree. The work itself is safe in `chat_session_events`, which is why recovery must offer "restore default layout" rather than SQL._ **§4 is closed** — `64961d4` (the boundary), `ef036df` (validate-on-read and the `'[]'` default), `92b8905` (validate-on-write). "A layout is an object" is now stated in four places: the column, the route, the read, and the renderer's willingness to survive being handed something else anyway. - [x] **Add an error boundary.** `grep -rln "componentDidCatch\|getDerivedStateFromError\|ErrorBoundary\|errorElement" src` returned **nothing** across the whole repo. **Resolved `64961d4`** — two of them, because "recover" means different things at different depths. `components/ErrorBoundary.tsx` is a generic render-prop class (`resetKeys` so a boundary cannot latch); `Screens/Dashboard/Layout/DashboardLayout.tsx` wraps the routed screen with the dock and header deliberately _outside_ it, so navigating away is itself a way out, and its fallback offers a two-click reset of every `screens/*` layout — dashboards are left alone, being user-created and holding content. `PanelSlot.tsx` wraps each app so one bad panel leaves the rest of the workspace running, with "clear this panel" as its recovery, offered only when the layout is the user's to edit. Not a targeted "reset _this_ screen": React unmounts the subtree before rendering a fallback, so an effect-based registry of "which layout key was I rendering" is empty at exactly the moment you need it. - [x] **Validate on read.** `useDashboardState.ts:36` was `key in state ? state[key] as T : defaultValue` — an unchecked cast over a value that arrived as `unknown` from jsonb. **Resolved `ef036df`** — `readValue()` checks kind-compatibility before casting and falls back to the caller's default, warning once per key. Not `isLayoutNode()`: all 24 layout call sites would have had to pass a predicate, and the same wrong-container bug applies to the `panelId → sessionId` maps. So the rule is generic and only guards **object-shaped defaults** — a wrong primitive is a cosmetic surprise, a wrong container is a crash. It deliberately does not write the correction back; a read should not overwrite the server, and the next real `setValue` repairs the row. - [x] **`layout` columns default to `'[]'`, which is not a valid `LayoutNode`.** `schema/dashboards.ts:13,31` — an empty **array** for a column holding an object. Any path that upserts without a layout (e.g. the `workspaces` branch) writes it; `key in state` is then true, so the stored `[]` wins over the caller's default and `normalizeLayout` calls `.children.map` on it and throws. **Creating a dashboard from the dashboard list is exactly that path**, so this was reproducible, not theoretical. **Resolved `ef036df`** — both columns are nullable with no default (NULL means "none stored", which is the truth), and `getAllDashboardState` omits the key when what is stored is not an object, so a row written before this is repaired by the next write instead of crashing the read. Verified live: creating a dashboard with no layout emits no `ws-layout` key, and a row hand-set back to `'[]'` is omitted too. `bun db:push` planned exactly the four expected `ALTER`s plus the two known-harmless `pk_music_now_playing` lines. - [x] **Validate on write.** The whole path is `unknown`: `useDashboardState.ts:46` → `servers/api/dashboards/dashboards.ts:45,83` → `queries/dashboards.ts:51,97` → cast `as never` at `:114` to satisfy drizzle → jsonb. No zod, no CHECK on either layout column. Given `databases/CLAUDE.md`'s stance that the schema is the source of truth for _contents_, a CHECK on `jsonb_typeof(layout) = 'object'` is the cheap half. **Resolved `92b8905`** — both halves, because they do different jobs. `ck_dashboards_layout_object` / `ck_screens_layout_object` are the backstop: nothing reaches those columns without passing them, including a psql session or a future writer nobody has written yet. NULL stays legal — it means "none stored", which is the honest state of a dashboard created without a layout. But a constraint violation surfaces as a 500 that tells the caller nothing, so the PATCH dispatcher checks the same rule first and answers `400 "ws-layout-x" must be a layout object`. Deliberately **not** a full `LayoutNode` schema: this is the wrong-container class of bug — the one that crashes `normalizeLayout` — and a structural validator would need the client's `zoom`/`config` vocabulary in the database layer to say anything more. Verified live: `db:push` planned exactly the two `ADD CONSTRAINT`s plus the known `pk_music_now_playing` churn and was stable on a second run; `update … set layout = '[]'` and `= '3'` are both rejected by Postgres; array, number and string bodies to `ws-layout-{id}` and `screens/{name}` all 400, and an object still round-trips. - [x] **A bare number is squatting in a framework namespace.** _(verified in the live DB)_ `apps/Soulseek/shared.ts:12` built `screens/soulseek-zoom/${panelId}` and passed it to `useDashboardState`. The server routes `^screens/(.+)$` into `screens.layout`, so: `user_id 1 | soulseek-zoom/soulseek-view | jsonb_typeof = number`. That namespace belongs to layouts. **Resolved `ba664dc`** — Soulseek's private zoom became a framework feature (`LayoutPanel.zoom`), so the scalar now rides on the layout node inside `screens/soulseek-v2` and needs no key of its own. The squatting row is gone: `select name from screens` returns 15 rows, none `soulseek-zoom/*`. This is also the general answer for per-panel scalar prefs — put them on the node, not in a key, because `useDashboardState` seeds a row per key on mount. --- ## 5. The framework work proper ### 5.1 Give panels a lifecycle — the highest-value change here - [x] **A close hook, invoked by the mutators, not by unmount.** — done `198dc71`. `components/Workspace/types.ts:38-47` had no close hook; the only `onClose` was `PanelComponentEntry.onClose` (`:55`), which is a header-button handler for _ephemeral_ panels and is suppressed on mobile (`PanelSlot.tsx:382`). So the two ways a panel dies — `removePanel(root, id)` and `setApp(root, id, null)` (the red traffic light, `PanelSlot.tsx:295`) — were pure tree rewrites that notified nobody. Shipped as `usePanelClose(panelId, handler)` rather than a registry field: what needs releasing is known to the component, not to the registry entry, and `CommandTerminalWrapper` shares one registry key across several panels with different sessions. `WorkspaceView` fires it from `handleRemove` and from `handleSetApp` when the app actually changes, and from nowhere else. Registration is never torn down — honouring an unmount would reintroduce the exact bug — and handlers are stamped with the workspace they were registered on so one dashboard's panel id cannot fire another's. **Strike the implementation this item used to suggest** ("diff removed panel ids old-tree ∖ new-tree"). It does not work, and `layout-utils.test.ts` now pins why (`04371a9`): `movePanel` inserts through `newPanelFrom`, which mints a fresh `uid()`, so a dragged panel's id is absent from the new tree while its app is still on screen; and `swapPanels` exchanges `{appType, config}` between two ids that both stay put, so a swap reads as two closes. **A panel id is a position in the tree, not an app instance**, and a diff of positions cannot answer a question about instances. The second half of the suggestion — have the mutators report it — is what landed, in the form of firing at the call site that already knows the user asked for a close. This is the thing `apps/Terminal/TerminalWrapper.tsx:31-38` asked for in writing: *"Killing on unmount is not an option until the panel system can tell a real close from an incidental remount."* It closes the terminal orphan leak as a consequence rather than as a special case, and the same gap affects every panel holding a server-side resource. **The requirement inverts for a chat panel** *(2026-08-07)* — do not wire one into this hook without deciding first. `agent-coordination.md` §5 Q2: idle reaping deliberately leaves the `sessionKey → claudeSessionId` pointer intact, but the explicit `disconnect` path calls `clearClaudeSession`, which destroys it and orphans the transcript. A panel is a pointer to a server-side session; **closing the window must not delete what it points at.** What coordination wants from `onClose` is a guarantee that nothing rides the disconnect path, not an eager cleanup. `ChatPanelWrapper` therefore does **not** call `usePanelClose`, and that is a decision, not an omission — the hook's own doc comment says so, so the next person to add one reads it there. - [x] **Then: kill the pty on real close.** — done `c92b51c`. The three wrappers now share `useTerminalSession`, which drops the map entry and `DELETE`s the session from `usePanelClose`. Two things fell out of doing it. `HostTerminalWrapper` still had the unmount cleanup the other two had removed, so it had been orphaning a host shell on every layout or route change. And `RunningShells` — the panel that exists to make orphans visible — was calling `/terminal/sessions`, while the proxy strips `/api/terminal` and the sidecar only answers under `/_officer`; verified live, `/sessions` returns `{"error":"not found"}`. That panel had always read "No shells running" and its kill button had always been a no-op. - [ ] **Then: reap orphans in the sidecar as a backstop.** `sidecars/pty/sessions.mjs:127-130` `detach()` never checks `clients.size === 0`; there is no idle timeout and no session cap. `lastActivityAt` is written (`:110`) and displayed (`:167`) but never read by a timer. Each orphan costs a `SHELL -i` with the owner's full env plus up to `BUFFER_MAX = 512 KiB` (`:10`) — bounded per session, unbounded in aggregate. _Note: `sidecars/` is platform, so in scope — but confirm before touching the pty protocol._ ### 5.2 Stop the avoidable remounts _Tier C — **the largest downgrade in the re-rank** (`agent-coordination.md` §6.4). A remount used to threaten whatever the panel was holding; a panel now holds nothing. A chat panel that remounts re-runs `resume-cursor` against the durable log and replays, costing latency, which §2 of the north star declares free. Fix these for the interaction quality they are genuinely about — scroll position, media playback, transcodes — not as a prerequisite for agent coordination._ **Measured `56ca411`.** `WorkspaceRenderer.test.tsx` mounts the real renderer against a mount-counting probe app and lets the real `layout-utils` mutators produce the "after" tree. The table below was written from reading the code; the test disagrees with its *diagnosis* in every row, and found one row it had missed entirely. Read this paragraph before acting on the bullets underneath it. - **The key is not the cause.** A panel's React identity is its position plus `key={child.node.id}` on its nearest ancestor group slot, but in each remounting case the **element type** at that position also changes — `PanelSlot` becomes `ResizablePanelGroup`, or the reverse — and React reconciles by type before it looks at keys. Reusing the panel's id so the key does not flip would therefore have changed nothing, at the cost of putting a panel id and a group id into collision, which now matters because a panel id is an agent's address (`agent_panels`). - **The row that was missing was the only cheap one, and it is fixed.** `ChildEntry` returned `<>{children}` for the first child and `<>{children}` for every other, so a panel sat in fragment slot 0 when first and slot 1 when not. Remove the leftmost of three panels and the second one found a `ResizableHandle` in its old slot and remounted — for nothing that happened to it. The handle slot is now always present, holding `null` when unneeded. - **What is left is genuinely structural.** Wrapping a panel in a group, and a two-child group collapsing to its survivor, both change what kind of thing lives at that position. The only fix that survives contact with React is the one the last bullet of this section already points at: render panels from a host that does not move when the tree reshapes, the way maximize is a CSS toggle on the same element. That is a redesign, not a patch, and it is still Tier C. The original table, kept because its *observations* hold even where its explanation did not: | operation | remounts? | why | | ------------------------------------- | ---------------------- | ------------------------------------------------------------------------- | | split, direction **matches** parent | no | `layout-utils.ts:34-44` splices children through by reference | | split, direction **differs** / leaf | **yes** | `:20-30` wraps in a new group with a fresh `uid()` | | split the root when root is one panel | **yes, everything** | `WorkspaceRenderer.tsx:40` renders one _unkeyed_ child whose type changes | | remove from a 2-child group | **yes — the survivor** | `:68-70` collapses the group, re-keying the sibling | | swap | apps remount | `setApp` twice; the component _type_ at each slot changes | | resize / maximize | no | ids preserved; maximize is a CSS toggle | | mobile panel switch | yes, by design | only the active child renders | | **any ephemeral panel on mobile** | **yes — every panel** | `WorkspaceView.tsx:165` replaces the workspace instead of overlaying | | **viewport crossing 768px** | **yes, full** | `useIsMobile` flips the branch at `WorkspaceView.tsx:165` | | **a panel stops being second** | **was yes — fixed** | `ChildEntry`'s fragment slots shifted under it (`56ca411`) | - [ ] ~~**Reuse the panel's id when wrapping it in a new group**, so the ancestor slot key doesn't flip. Kills rows 2 and 3.~~ **Withdrawn `56ca411`** — measured, and it kills neither. The element type at that position changes too, which React acts on first. It would also collide a panel id with a group id, and a panel id is an agent's address now. - [ ] ~~**Don't re-key the survivor when a group collapses** (`layout-utils.ts:68-70, 83-88`). Kills row 4.~~ **Withdrawn `56ca411`**, same reason: the survivor changes type as well as key. - [ ] **Overlay the mobile ephemeral panel instead of replacing the workspace** (`WorkspaceView.tsx:165`). Affects `/files`, `/email`, `/chat`, `/browser`, `/dashboards`. - [ ] **Reference for how it should feel:** maximize (`PanelSlot.tsx:430-457`) is a CSS state toggle on the same element — no portal, no remount, scroll position and media playback preserved. Every mutator should be held to that. ### 5.3 Drag-to-move: finish it or delete it - [ ] **Decide, then act — do not patch it.** `dragSourceId` can never become non-null: the only code that would set it is commented out at `PanelSlot.tsx:240-256`. So the whole path is dead: `DragOverlay.tsx` (99 lines, imported by nothing), `LayoutEditor.tsx` (51, imported by nothing), `movePanel` + `insertPanel` + `DropPosition` (`layout-utils.ts:142-169`), and three context fields. ~180 lines. **If finishing it:** `movePanel` mints a _brand-new_ panel id, so it destroys all panel-keyed state, and `PanelContents` (`layout-utils.ts:229`) carries only `{appType, config}` — so a move **silently drops `fitContent` and `zoom`**. Fix before re-enabling. **Downgraded 2026-08-07** — this was on the critical path in `agent-coordination.md` §1.5 (P3: "dragging a panel would silently sever its session binding") and no longer is. Q3 made the agent's _name_ the address and the panel id merely where it lives, and `e588524` made move and swap carry `config` with the panel. `useAgentPanel` resolves by name and re-anchors the row afterwards. Still worth deciding — it is dead code — but it gates nothing. See `agent-coordination.md` §6.4. ### 5.4 Make `normalizeLayout` framework, not convention - [x] **One normaliser applied inside `WorkspaceView`.** _(`1de1d92`)_ — it landed as a prop rather than a factory: ``, with `normalizeLayout` in `layout-utils.ts` and the persist-back inside `WorkspaceView`. All fourteen copies are deleted; QrTransfer gained the persist-back it never had. Two notes for whoever reads this next. The framework normaliser **drops `config`** when it replaces an app — the copies kept it, which left the old app's config on a panel the new app now owns, the opposite of `setApp`. And Headscale keeps a local `useMemo`, because its check is "is the server picker present at all", which is about a panel being _missing_ and no allow-list can see that. Still open from this item: deriving the allow-lists from the AppRegistry (they are still hand-written literals, so a type still allow-listed but deleted from the registry passes and reaches the unrecoverable empty box at `PanelSlot.tsx:311-317`). The unguarded screens are done (`653201f`): Dashboards, Desktop, Terminal and Files now pass one, checked against what is persisted rather than against their defaults; Browser and Email deliberately do not, because their panels resolve through `components`, which `PanelSlot` keys on the panel id, so their `appType` is never read. Home and the two dashboard screens are not `locked` and stay open. The original text follows. **One `makeLayoutNormalizer(allowed, fallback)` applied inside `WorkspaceView`.** The guard currently exists **14 times, character-identical except for the allow-list and the fallback**, plus a matching `useMemo`/persist-back `useEffect` pair 13 times — ~150 duplicated lines. Consequences of it being convention: - **10 `WorkspaceView` consumers have no guard at all**, including `screens/HomeScreen.tsx:11`, which also omits `locked` — the one screen where a user can set any registry appType with nothing pinning it back. - Allow-lists are hand-written literals, never derived from the AppRegistry. They catch a _renamed_ appType; they do **not** catch one still allow-listed but deleted from the registry — that passes and reaches `PanelSlot.tsx:311-317`, which on a `locked` screen renders an empty teal-bordered box with no picker and no way for the user to recover. - `screens/QrTransferScreen.tsx:19-39` has the guard but no persist-back, so it re-normalises on every mount forever and never heals the row. - [x] **~~Then collapse the three default-layout mechanisms~~ — inventoried and dropped.** Per-screen `defaultLayout.ts` (21, not 20 — `Home/defaultLayout.tsx` is misnamed), `createDefaultLayout()` in the core, and the 6-entry template array at `DashboardPreview.tsx:33-142`. They are not three copies of one mechanism. `createDefaultLayout()` is a one-liner meaning "the empty state of a workspace" and the templates are the picker for a *user-created* dashboard, where the user chooses the apps afterwards. The 21 files are *built-in locked screens*, where the apps are fixed. Collapsing across that line would merge two different questions. Nor are the 21 duplication. Fourteen share a shape — flat horizontal split, nav on the left — but across seven different size pairs, with panel ids that other code hardcodes (`components` maps, `mobilePanelId`, `ChatPanelWrapper panelId=…`, and now the `appTypes` allow-lists). A `splitH(...)` helper would turn 11 lines into 1 without removing a single decision: still 14 call sites, still 14 argument sets, plus a layer between "what does /music look like" and the answer. That is compression, not deduplication. What the inventory did turn up, none of which is an abstraction: - **`DashboardPreview`'s edit path reset the layout on every submit** — renaming a dashboard or editing its description threw away the panel arrangement, and dropped the terminal maps on a rename. Fixed and verified against the running server (`cd1f161`). - `Home/defaultLayout.tsx` is a `vertical` group with one child at `size: 100` — a bare panel with a wrapper that does nothing, unlike Files/Terminal/Desktop next to it. Cosmetic: the persisted `screens/home` row is what actually renders, so changing it changes nothing today. - Browser and Email are the one genuine copy-paste pair (same nesting, same 25/75 and 60/40, same trailing chat panel). One duplicate, and the two screens are diverging anyway. ### 5.5 Persistence hygiene _Three Tier A items live here (`agent-coordination.md` §6.2, A5 and A7). The two lost-update bugs are worse than described now that identity is in the layout: a debounce timer closing over a pre-drag tree does not just resurrect a deleted panel, it **re-writes an older `config`**, so a panel that was just named reverts to anonymous. And the never-invalidated cache means two windows onto the same server-side work disagree permanently about the roster, with neither told — a direct contradiction of §5 Q1._ - [x] **The resize debounce can resurrect a deleted panel.** `WorkspaceRenderer.tsx:108-124` held a 500 ms timer in a ref with **no `useEffect`, therefore no cleanup**, and its callback closed over the layout as it was when the drag began. Drag a splitter, remove a panel within 500 ms → the timer PATCHed the pre-deletion tree and the panel came back. Same shape for a split. **Resolved `b0a32ae`** — the timer now lives behind a `useEffect` that **flushes** it on unmount rather than dropping it: with the write expressed as an updater the early write is correct, and dropping would lose a splitter drag made just before navigating away, which the no-cleanup version did at least persist. - [x] **Concurrent same-key writes clobber.** A window resize fires `onLayout` on every group at once; each scheduled its own timer against the same base tree and the last won (`WorkspaceView.tsx:76-81`). **Resolved `b0a32ae`** — all eight mutations in `WorkspaceView` pass an **updater** to `setValue` (`onLayoutChange((prev) => …)`) instead of a tree computed from the `layout` their callback closed over, so each composes against the current cache. The no-op guards (`countPanels`, the `=== layout` identity checks) still test the rendered `layout`: they only decide whether a write is worth making, and being one render stale there costs a redundant no-op write at worst. Worth keeping in mind for anything new that writes the layout: **compute from `prev`, always.** The cost of getting it wrong is no longer a size that snaps back — it is an older `config`, so a panel that was just given an agent's name reverts to anonymous and the agent stops being addressable. - [x] **The cache is never invalidated.** `staleTime: Infinity` and no `invalidateQueries` anywhere in the repo. Meanwhile every PATCH computed and returned a full fresh state blob which the client **discarded** — 3 SELECTs per splitter release, thrown away. **Resolved `81ad3ef`** — both halves. The PATCH returns `{ok: true}`; nothing had ever read that body, and a caller that did would be reading state assembled *before* whatever concurrent write it raced. The client refetches **on focus**, with three non-default guards, because this cache is optimistic: a refetch that started before an in-flight PATCH landed would overwrite the value already on screen — the same lost-update shape as the two items above, and self-healing only until the next mutation composes on top of the stale tree. So `refetchOnMount: false` (splitting a panel mounts a fresh consumer, which is exactly when a write is in flight), `refetchOnReconnect: false`, and `refetchOnWindowFocus` gated on a module-level in-flight count plus a 2 s quiet period. - [x] **Preserve sibling sizes on split.** `splitInner`/`insertPanel` redistribute evenly (`100 / newChildren.length`), so one split discards carefully tuned proportions. **Resolved `abea7a3`** — the new sibling takes half of the *target's* size and nothing else moves. One helper serves both call sites, because the drop path (`movePanel` → `insertPanel`) carried the identical bug. Two of the three tests were already in `layout-utils.test.ts` asserting the even split, written to the old behaviour deliberately; they now assert the new one. The third documents the interaction worth knowing: `removePanel` renormalises the group as the panel leaves, so a move reads as renormalise-then-halve, not halve alone. - [x] **`tpl-N` panel ids collide across dashboards.** `DashboardPreview.tsx:25-26` — `let tplCounter = 0; const tplUid = () => \`tpl-${++tplCounter}\`` — module-level, no entropy, resets every page load. Two dashboards created from templates after a reload hold panels with **identical ids**, and panel id keys `terminal-conn-${panelId}`and`file-viewer:${panelId}`. **Resolved `6fd60e5`** — the templates now call the core's `uid()`, which is exported from the Workspace barrel for the first time so that there is exactly one way to mint a panel id. The duplicate minter is deleted rather than fixed: a second implementation of "make me an id" is how this happened, and the collision was no longer only a settings mix-up — `agent_panels` addresses a panel by `(dashboardId, panelId)`, so two dashboards built from templates in the same page load could hand two different agents the same address. ### 5.6 Registry - [x] **No duplicate-key guard.** `metasToRegistry` is `Object.fromEntries` (`AppRegistry/useAppRegistry/useAppRegistry.ts:19`) — a collision silently last-wins and one app just disappears. **Resolved `6fd60e5`**, but not by throwing, which is what this item asked for. A duplicate key is an authoring mistake made at edit time; throwing punishes the owner at runtime for it, by taking down every dashboard rather than one app. So it is a **test over the real meta list** (`AppRegistry.test.ts`) plus a `console.error` at runtime — the mistake is caught before it ships and named if it somehow does. Confirmed: all 44 keys are unique today, and the test says so. Getting the real list into a test needed one thing beyond exporting it: `test-setup.ts` was not providing `localStorage`, and `MusicPlayer/useLyricsOpen.ts` reads it at *import* time, so the whole app graph was unimportable from a test. That is now fixed, which unblocks testing anything else that pulls in a panel app. - [x] **Seeding depends on undocumented mount ordering.** Three call sites call `useAppRegistry()` with no argument, defaulting to `[]`. It works only because `` sits at `frontend.tsx:32`, above `` at `:34`. Mount a `WorkspaceView` above that and every panel renders empty. **Resolved `9fcc9c2`** — and the mechanism is worse than "ordering", which is why the fix is not "move the component up". `` seeded through `useGlobal`'s `initialData`, and **`initialData` is not a write**: it applies only to whichever component reads the slot first. A `WorkspaceView` that rendered first would create the slot as `{}` and the seeder had no second chance — every panel on that screen an empty box, for a reason visible nowhere near it. Both registries are now written into the query cache by `seedAppRegistry` / `seedWidgetRegistry` before `createRoot().render()`, so there is no ordering to depend on. They take the `QueryClient` rather than running as a module-scope side effect because the app list imports every panel app and every panel app imports the Workspace framework; keeping the call in `frontend.tsx` — the one module that is nobody's dependency — is what stops that being an import cycle. (Making `useAppRegistry` simply default to the static list was the obvious fix and is exactly that cycle.) `registerApp` and `registerWidget` are deleted with the components: nothing ever called either, and a registry that can be added to at runtime is a registry whose contents depend on what has mounted. - [x] **`officerdev/file-viewer` is a dead registration.** Its provider reads `usePanelChannel('file-viewer:' + panelId)` and **nothing in the repo writes that channel**. Also `availableOnPanel: false`, so it can't be picked. If it ever appeared in a layout it would say "No file selected" forever. **Resolved `9fcc9c2`** — traced and confirmed dead, then removed rather than repaired. The file viewer that users actually see is mounted by `useFileViewerPanels` as an *ephemeral* panel, which supplies `FileViewerBody`/`FileViewerHeader` itself with a provider reading the path from `?view=`/`?ephemeral=` — it never touched the registry. No stored layout referenced the key (checked across `dashboards`, `screens`, `dashboard_defaults`, `user_state`, `user_settings`: zero rows), so the meta and `FileViewerPanelWrapper.tsx` are gone. Side effect worth knowing: no app in the registry now uses the `provider` field. It is kept, because the ephemeral path (`PanelComponentEntry.provider`) still does and `PanelSlot` resolves the two symmetrically. - [ ] **`dashboard-list` is pickable in every panel on every dashboard.** `apps/Dashboards/index.ts:12-16` omits `availableOnPanel` while its sibling `dashboard-preview` sets `false`. Almost certainly unintended — the flag is opt-_out_, and 12 of 44 metas omit it. Consider making it opt-_in_. ### 5.7 Effect hygiene in panel apps All the same bug: an app guessing "am I being closed?" from an unmount, or paying for a remount from 5.2. - [ ] **PARKED — `useClient` identity / `DesktopView` deps.** Revisit later, not now. `useClient` returns a fresh object every render (`workspaces/hooks/src/useClient.ts:30-38`), but it is consumed by calling verbs at call time, which is identity-agnostic. **Do not memoize it.** Only two dep-array sites exist: `apps/Desktop/DesktopView.tsx:205` (one redundant connect at mount — React bails on the unchanged `setStatus`, so it settles rather than looping) and `hooks/useChat.ts:124` (a `useCallback`, harmless). Owner has used this pattern for years without issue; my first write-up called it a live bug and that was overstated. - [x] **`DictateDialog` never releases the microphone.** — _resolved `c0fae47`_ `return () => { if (!showDictate) cleanup(); }`. The cleanup that runs on `true → false` is the one registered by the `true` render, where `showDictate` is `true`, so it never fires. Mic stream, `AudioContext` and the rAF loop leak. `apps/QrTransfer/Receiver.tsx:120` is the correct version. Fixed by dropping the guard and reading `cleanup` through a ref, so the teardown runs on close and on unmount and is the current one either way. `cleanup` also had to become safe to call twice — the success path in `stopRecording` releases the hardware early, and closing an already-closed `AudioContext` rejects. - [x] **`useAudioRecording` has no unmount cleanup at all** (`apps/Chat/useAudioRecording.ts` — no `useEffect`). Unmounting Chat mid-recording leaves the mic open for the life of the tab. — _resolved `c0fae47`_, and pinned by `useAudioRecording.test.tsx`: the hook is rendered, put into recording, and unmounted, and the test asserts the track was stopped. - [x] **`HostTerminalWrapper` still has the cleanup the other two deliberately removed.** — _resolved `c92b51c`_, before this section was re-read. All three wrappers now share `useTerminalSession`, which keeps the `panelId → sessionId` map across unmounts and drops it on a real `usePanelClose` — the §5.1 signal is what made a correct answer possible. - [ ] **REVISED — `useTaskRunner` does not abandon the running task; it kills it.** The original entry was wrong twice, both times by reading only the hook. `stop` **is** sent — `TaskRunnerModal.tsx:1320` renders a Stop button while `phase === 'running'`. And a bare `ws.close()` is not abandonment: `task-executor.ts:303-309` kills the process tree on socket close, the same `killTree` the Stop button reaches. What is true is the last clause: there is no re-attach, so an inline run dies with its modal. That is defensible — inline is the *ephemeral* mode and the job path exists for everything else — so this is left alone deliberately rather than left undone. - [ ] **`VideoPlayer` kills the transcode on incidental unmount.** `apps/Jellyfin/VideoPlayer.tsx:217-223` POSTs `stopped`, killing server-side ffmpeg, then renegotiates. Fires on every "yes" row in 5.2 — one row fewer since `56ca411`. Left as is: the player renegotiates from scratch on remount anyway, so the stop is correct, only expensive. The real fix is 5.2's, not this file's. The misleading comment at `:215-216` is corrected in `c0fae47`: `sendReport` is `useCallback(…, [])`, so naming it is equivalent to an empty list — and that is now written down as a constraint, because if it ever grows a dependency this becomes the Continue Watching bug again. - [x] **Two stale-closure sockets.** — _resolved `c0fae47`_, both with the ref pattern rather than by restarting the socket. `usePipelineRunner` kept the first render's `handleEvent`, whose `flushStream` carries a captured `streamingText`; `AudioStreamPlayer` kept the first `onError`. - [x] **`PanelSlot` defines a component inside render.** — _resolved `c0fae47`_. `DefaultHeader` is gone: the header is now an element, not a component type, so there is nothing for React to fail to match. - [x] **The context value is a fresh literal.** — _resolved `c0fae47`_. `useMemo` over the eighteen members. Note what it does *not* buy: the value still changes whenever `layout` does, because half the callbacks close over it. What it stops is the renders that change nothing a panel can see — the ephemeral pane opening, a mobile panel switch, every frame of a maximize animation. ### 5.8 Navigation — finish the refactor - [x] **Move the seven channel-driven apps' selection into the URL.** _Six of the seven are done; the seventh (Chat detail) is chat-owned and deliberately untouched — see the foot of this item._ Split when this was written: 11 URL-driven (everything post-refactor), 7 channel-driven, 3 on bare `useState`. The channel-driven set: Music (`music:cwd`), Soulseek sections, SystemMonitor (`monitor:scope`), Chat detail (`chat:selected-session`), Email, Browser, and all five Settings pages (one fix point, `SettingsPanel.tsx:56`). **This is chronological, not architectural** — panels render as ordinary children of the screen's Route element (`PanelSlot.tsx:333`), so every one of them can call `useParams` today. Nothing in the framework needs to change. Symptom: `/soulseek` reopens in your last section and `/music` at your last album while the URL says the bare route. `usePanelChannel` is a slot on **one process-global QueryClient** (`frontend.tsx:15-21`) with no per-route scoping, and `reset` is called nowhere. Authority: `docs/navigation-audit.md`. **Settings is done** (audit M6). Five pages moved to `/settings/:page/:section`: the section is `useParams`, the sidebar entry is a `` instead of a `