Files
kandev/docs/specs/dockview-empty-task-recovery/plan.md
T

213 lines
10 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Plan — Dockview Recovery for Sessionless Task Switches
> Implementation plan for the `dockview-empty-task-recovery` spec.
> Workflow: TDD (Red → Green → Refactor) per `.claude/skills/tdd/SKILL.md`.
## 1. Overview
Tasks created via the kandev MCP tool with `start_agent=false` have no session/environment.
Selecting such a task in the task-details sidebar today causes:
1. The Dockview layout to corrupt (wrong widths on the central group).
2. The top bar (task title, branch) to stay on the previous task.
3. The corruption to persist across subsequent task switches because the broken
layout is saved back to per-session storage.
Goals:
- Make sessionless task selection update the active task, URL, and Dockview layout deterministically.
- Detect a corrupted Dockview layout after restore and self-heal by rebuilding the default.
- Cover with one E2E test (mock-agent + MCP `create_task_kandev` with `start_agent=false`)
and targeted unit tests on the restore + switch logic.
Out of scope:
- Refactoring `task-session-sidebar.tsx` beyond what the fix requires.
- Changing how layouts are persisted to storage.
- Touching backend MCP behavior beyond the existing `start_agent=false` path (already correct).
## 2. Prerequisites
- No DB migrations or config changes.
- The mock-agent's `e2e:mcp:kandev:create_task_kandev(...)` already works
(`apps/backend/cmd/mock-agent/script.go:120`, `executeMCPCommand`); the new test
exercises that path with `start_agent: false`.
- `__dockviewApi__` is exposed on `window` for E2E inspection
(`apps/web/lib/state/dockview-store.ts:614`).
## 3. Implementation Steps
### Step 1 — Failing E2E: sessionless-task selection (RED)
Description: write the spec that reproduces the bug end-to-end.
- **File (new)**: `apps/web/e2e/tests/task/sessionless-task-switch.spec.ts`
- Flow:
1. Seed task A with an agent (`apiClient.createTaskWithAgent`,
`description: "/e2e:simple-message"`).
2. Navigate to task A; wait for `session.idleInput()` and stable layout.
3. Use the agent to create task B sessionless via mock script:
`e2e:mcp:kandev:create_task_kandev({"parent_id":"self","title":"Empty Task","description":"…","start_agent":false})`
(mock-agent forwards to the real MCP handler).
4. Click task B in the sidebar via `session.clickTaskInSidebar("Empty Task")`.
5. Assert breadcrumb shows "Empty Task" within 10s.
6. Assert URL matches `/t/<taskBId>`.
7. Assert Dockview central group width ≥ a sane minimum (use a new helper,
see Step 2). Specifically: no group in the live grid has `width <= 1` and
the sum of root children widths ≈ `api.width`.
8. Click task A back: `idleInput()` becomes visible again and central group
widths remain valid (regression on layout-corruption persistence).
Expectation: this test fails on `main` (title stays on A, central group width is broken).
### Step 2 — E2E helper: layout sanity assertion
Description: add a small helper to assert no Dockview groups have zero/near-zero width.
- **File (modify)**: `apps/web/e2e/pages/session-page.ts`
- Add method `expectLayoutHealthy()` that does a `page.evaluate` on `__dockviewApi__`,
walking `api.groups` and asserting `g.width > 1` for every group, and that
`Math.abs(sum(rootChildrenWidth) - api.width) <= 4` (rounding tolerance).
- Reuse `expectNoLayoutGap()` patterns where possible — keep additions <40 lines.
### Step 3 — Failing unit test: `tryRestoreLayout` rejects corrupted layouts (RED)
Description: pin the contract that a structurally-broken saved layout is discarded.
- **File (new)**: `apps/web/components/task/dockview-layout-restore.test.ts`
- Cases:
- Returns `false` when `getSessionLayout` yields a layout where any leaf has
`views: []` after sanitization (covered today by `cleanNode` returning null,
keep as a regression).
- **NEW failing case**: returns `false` when the sanitized layout's
`grid.root.size <= 0` or any branch child has `size <= 0` (zero-width groups).
- Mock `getSessionLayout` from `@/lib/local-storage` and `applyLayoutFixups`
from `@/lib/state/dockview-layout-builders` (mirror existing
`dockview-session-switch.test.ts` mock style).
### Step 4 — Implement layout sanity check in `sanitizeLayout` (GREEN)
Description: extend the existing sanitizer to reject grids with zero/missing sizes,
so a corrupted persisted layout is dropped instead of restored.
- **File (modify)**: `apps/web/components/task/dockview-layout-restore.ts`
- Add an internal `hasValidSizes(node): boolean` walker:
- For `leaf`: `typeof node.size === "number" && node.size > 0` (or size missing
and parent is the root single-leaf — handle by treating undefined size at root
as valid since dockview infers it from container width).
- For `branch`: every child `hasValidSizes` and `children.length > 0`.
- In `sanitizeLayout`, after `cleanNode` produces `cleanedRoot`, return `null`
when `!hasValidSizes(cleanedRoot)`.
- This causes `tryRestoreLayout` to fall through to the default-build path.
### Step 5 — Failing unit test: sidebar select-task always updates store + URL for sessionless tasks (RED)
Description: lock down `handleSelectTask`'s contract for the sessionless branch.
- **File (new)**: `apps/web/components/task/task-session-sidebar-select.test.ts`
- Extract the pure decision into a testable helper (see Step 6) and assert:
- When `prepareAndSwitchTask` resolves `false` (no session created), the helper
invokes `setActiveTask(taskId)` AND calls `performLayoutSwitch` with the old
session and a sentinel "reset" path (or equivalent: triggers
`resetLayout()` — see Step 6).
- URL is replaced exactly once (mock `replaceTaskUrl`).
- The `oldSessionId` captured before `launchSession` is the one passed to
layout-switch (regression on the comment at lines 322–325).
### Step 6 — Implement sessionless-switch fix (GREEN)
Description: when no session can be created, explicitly tear down the prior
session's layout instead of leaving it stale.
- **File (modify)**: `apps/web/components/task/task-session-sidebar.tsx`
- In `prepareAndSwitchTask` (lines 316–345), when `launchSession` returns no
`session_id` OR throws: before returning `false`, call a new helper
`releaseLayoutForTask(oldSessionId)` that:
- Saves the outgoing session's layout (already handled by
`switchSessionLayout` when passed both args), then
- Calls `useDockviewStore.getState().resetLayout()` which builds the default
layout via `buildDefaultLayout(api)` (`dockview-store.ts:664–667`).
- In `handleSelectTask` (lines 445–476), the `if (!switched) setActiveTask(taskId)`
branch must run BEFORE the next paint (it already does, but ensure
`replaceTaskUrl` is called in both branches — currently fine).
- **File (modify)**: `apps/web/lib/state/dockview-store.ts` — no API change; we
reuse `resetLayout`. If a small helper export is cleaner, add
`releaseSessionLayout(oldSessionId)` that wraps `saveOutgoingSession` +
`resetLayout` and is called from the sidebar.
### Step 7 — Optional backend test (only if needed)
Description: only add if Step 1's E2E reveals the mock-agent path doesn't propagate
`start_agent=false` correctly. Otherwise skip — the existing
`TestCreateTask_ToolSchema_HasParentID` already locks the schema.
- **File (modify)**: `apps/backend/internal/agentctl/server/mcp/handlers_test.go`
- Add `TestCreateTask_StartAgentFalse_DoesNotAutoStart` that asserts the
forwarded payload includes `start_agent: false` when the tool arg is `false`.
### Step 8 — Verify (REFACTOR + sign-off)
- Run from `apps/`:
- `pnpm --filter @kandev/web test -- dockview-layout-restore` (unit).
- `pnpm --filter @kandev/web test -- task-session-sidebar-select` (unit).
- `pnpm --filter @kandev/web e2e -- sessionless-task-switch` (E2E).
- Run `make -C apps/backend test` if Step 7 was needed.
- Run `make fmt` then `make typecheck test lint` per AGENTS.md.
## 4. File Changes Summary
Created:
- `apps/web/e2e/tests/task/sessionless-task-switch.spec.ts`
- `apps/web/components/task/dockview-layout-restore.test.ts`
- `apps/web/components/task/task-session-sidebar-select.test.ts`
Modified:
- `apps/web/components/task/dockview-layout-restore.ts` — add `hasValidSizes` and
reject corrupted grids in `sanitizeLayout`.
- `apps/web/components/task/task-session-sidebar.tsx` — extract testable helper;
release layout when sessionless task is selected.
- `apps/web/lib/state/dockview-store.ts` — optional `releaseSessionLayout` export
(only if it improves call-site clarity).
- `apps/web/e2e/pages/session-page.ts` — add `expectLayoutHealthy()` helper.
- `apps/backend/internal/agentctl/server/mcp/handlers_test.go` — only if Step 7
is required.
Deleted: none.
## 5. Testing Strategy
Unit (vitest):
- `dockview-layout-restore.test.ts`: sanitizer rejects zero-size branches/leaves;
sanitizer keeps healthy layouts unchanged (snapshot-style structural compare).
- `task-session-sidebar-select.test.ts`: extracted `prepareAndSwitchTask` helper
releases layout + falls back to `setActiveTask` when launch fails; captured
`oldSessionId` is forwarded to layout-switch.
E2E (Playwright, `KANDEV_MOCK_AGENT=only`):
- `sessionless-task-switch.spec.ts`: covers the full bug scenario including
return-trip to the original task.
Manual smoke (one-off):
1. Start kandev in dev mode.
2. From the agent, run `create_task_kandev` with `start_agent=false`.
3. Click the new task in the sidebar — confirm top bar updates and the central
group keeps a sane width.
4. Click back to the agent task — confirm layout restored without artefacts.
## 6. Rollback Plan
- All changes are confined to frontend modules and one optional backend test.
- Revert by `git revert` of the merge commit; no DB migrations or persisted-format
changes (the sanitizer is strictly more conservative — it only rejects layouts
the app already cannot render).
## 7. Estimated Effort
- Complexity: **medium** (multi-layer fix: store + restore sanitizer + sidebar handler).
- Time: ~0.5–1 day including TDD cycle and CI fixups.