15 KiB
id, title, status, wave, depends_on, plan, spec
| id | title | status | wave | depends_on | plan | spec | |
|---|---|---|---|---|---|---|---|
| 08-conditional-pin-sync | Conditional pin sync | done | 5 |
|
plan.md | ../../specs/ui/requirements/agent-todo-list-panel.md |
Task 08: Conditional pin sync
Gate the automatic Todos pin on the "Only pin when todo list is not empty"
preference: when it is on, the sync hook must not add the todos panel while
the active session's todo list is empty, using the same two-source todo
fallback the panel content uses (live sessionTodos.bySessionId first, then
persisted todo messages via buildTodoItems). The sub-option never removes
an existing panel and never affects manual adds.
- Acceptance:
resolveConditionalTodoPanelActionreturns"none"(not"add") whenonlyPinWhenNotEmptyis true andtodoListNotEmptyis false and the panel is absent;"add"when the list is non-empty; and never"remove"as a result of the sub-option (removal stays gated solely onshowTodoListPanel).useSyncTodoPanelsubscribes to the active session's todo state (live slice + persisted messages) and re-runs the sync when it changes, so the panel appears as soon as todo entries arrive (live WS or hydrated history).- Unit tests go red before implementation and green after;
pnpm run typecheckpasses.
- Verification:
cd apps/web && pnpm exec vitest run components/task/dockview-todo-panel-sync.test.ts && pnpm run typecheck(fresh worktree bootstrap first if needed:cd apps && pnpm install --frozen-lockfile). - Files likely touched:
apps/web/components/task/dockview-todo-panel-sync.tsapps/web/components/task/dockview-todo-panel-sync.test.ts
- Dependencies: Task 07 (store field
showTodoListPanelOnlyWhenNotEmptyexists inUserSettingsState). - Parallelism:
sequential. - Inputs: Spec What / Scenarios sections
(
docs/specs/ui/requirements/agent-todo-list-panel.md); plan's "Conditional-pin sync" section;apps/web/components/task/todos-panel-content.tsxas the exact two-source fallback reference;buildTodoItems(apps/web/hooks/use-processed-messages.ts).
Implementation notes:
resolveConditionalTodoPanelActiongainsonlyPinWhenNotEmptyandtodoListNotEmptyparams; insert the new guard after the restoring/maximized guards and only in the add path:if (params.onlyPinWhenNotEmpty && !params.todoListNotEmpty) return "none";.syncConditionalTodoPaneloptions gain the same two params and pass them through.- In
useSyncTodoPanel, derive the active session's todo state:- live:
useAppStore((s) => (sessionId ? s.sessionTodos.bySessionId[sessionId] : undefined)) - persisted:
useAppStore((s) => (sessionId ? s.messages.bySession[sessionId] : EMPTY))thenuseMemo(() => buildTodoItems(messages), [messages]) todoListNotEmpty = (live?.length ?? 0) > 0 || messageTodos.length > 0Readlive.userSettings.showTodoListPanelOnlyWhenNotEmptyinside the effect (alongside the existingshowTodoListPanelread), pass both new values intosyncConditionalTodoPanel, and addtodoListNotEmpty+onlyPinWhenNotEmptyto the effect dependency array.
- live:
- Do not mount
useSessionMessageshere — the desktop workbench's chat panel always fetches the session's messages; subscribing to the store slice is enough and avoids duplicating fetch/subscription side effects. - Test additions: extend the
it.eachtable with{ showTodoListPanel: true, onlyPinWhenNotEmpty: true, todoListNotEmpty: false, panelExists: false }→"none"and the non-empty variant →"add"; add asyncConditionalTodoPanelcase assertingaddPanelis not called with the sub-option on and an empty list; assert an existing panel is untouched (noclose) in that case.
Results
Red first: extended resolveConditionalTodoPanelAction's it.each table
with 5 sub-option rows (empty list + sub on → "none"; non-empty → "add";
existing panel untouched; sub off → unchanged "add"; master off still
"remove") and added two syncConditionalTodoPanel cases (no addPanel with
empty list + sub on; addPanel with non-empty list). pnpm exec vitest run components/task/dockview-todo-panel-sync.test.ts → 2 failed (the empty-list
suppression rows returned "add"/called addPanel).
Implemented in components/task/dockview-todo-panel-sync.ts:
resolveConditionalTodoPanelActiongainsonlyPinWhenNotEmpty+todoListNotEmptyparams; new guardif (params.onlyPinWhenNotEmpty && !params.todoListNotEmpty) return "none";after the restoring/maximized guards, in the add path only — never affects"remove"or an existing panel.syncConditionalTodoPaneloptions gain both params and pass them through.useSyncTodoPanelsubscribes to the active session's todo state (sessionTodos.bySessionId[sessionId]live +messages.bySession[sessionId]persisted viabuildTodoItems), computestodoListNotEmpty = liveTodos.length > 0 || buildTodoItems(messages).length > 0, readslive.userSettings.showTodoListPanelOnlyWhenNotEmpty, passes both intosyncConditionalTodoPanel, and addsonlyPinWhenNotEmpty+todoListNotEmptyto the effect deps so the panel appears as soon as todo entries arrive. NouseSessionMessagesmount (chat panel fetches messages).- Test
DEFAULT_OPTIONSwidened withonlyPinWhenNotEmpty: false, todoListNotEmpty: falseso existingsyncConditionalTodoPanelcalls stay assignable.
Commands:
cd apps/web && pnpm exec vitest run components/task/dockview-todo-panel-sync.test.ts→ 23 passed (2 red → green).cd apps/web && pnpm run typecheck(withNODE_OPTIONS=--max-old-space-size=4096) → clean.
Reviewer-feedback refinement (adversarial review, APPROVE qualified)
The DeepSeek V4 Pro adversarial review (sub-task
4c855132-fc54-4e8c-924e-3a45bcda460b) found 3 items; two were acted on:
- N1 (minor, suspected) — the inner RAF callback captured the
render-time
todoListNotEmptymemo; a WS todo event landing between render and rAF dispatch (~16ms) could make the pin decision one frame stale. Fixed by extractingtodoListNotEmptyForSession(liveTodos, messages)(the panel's exact two-source fallback, exported so the contract is testable) and recomputing it inside the callback from the dispatch-timeappStore.getState()snapshot. The render-time memo stays as the effect's change signal in the dep array. Added 4 unit tests pinning the helper (empty, live-wins, persisted-fallback, empty-live-array-falls-through). - N3 (nit, confirmed) — dropped the now-unnecessary
as unknown as Partial<BackendMessageMap[...]>cast inlib/ws/handlers/users.test.ts(the field is statically typed). - N2 (nit, confirmed) — card-level
data-settings-dirtyon both toggles; fixed in the round-2 pass as F1 (per-field dirty flags, see Task 07 results). - F2 (minor, suspected, round 2) — the render-time
todoListNotEmptymemo and the RAF-dispatch recompute each calledbuildTodoItems(two O(n) scans per effect cycle). Fixed by removing the memo entirely: the effect's change signal is now the rawliveTodos/messagesslice identities in the dependency array (they only change when the underlying todo/message data actually changes), so the predicate is computed exactly once per sync — in the dispatch callback, from the dispatch-time snapshot.useMemoimport dropped.
Post-fix verification: sync+WS unit tests 49 passed; pnpm run typecheck
clean; make fmt + make lint clean; E2E
todo-list-panel.spec.ts 8/8 passed (web rebuilt). Committed as follow-up
fix: on the feature branch.
Round-4 reviewer feedback (OMP GPT Luna) and disposition
- Finding 1 (major, confirmed by reviewer): "branch contains unrelated
changes" — review-base artifact, not a defect: the reviewer diffed
against the stale local
mainref (c0f5750b); againstorigin/mainthe branch is exactly the four feature commits / 31 files (git diff origin/main...HEAD --stat). No action; round-5 brief instructs the reviewer to useorigin/mainas the base. - Finding 2 (major, confirmed): malformed persisted todo metadata crashes
buildTodoItems—metadata.todosas a non-array (object/primitive) throwsTypeError: ...?.todos?.map is not a function, and[null]elements throw onitem.text. The round-1 fix made this a sync hot-path call, so a malformed message would throw inside the RAF callback and the sync (including panel removal with the master pref off) would silently fail; the same throw also hits the panel content and chat processing, and violates the spec's "malformed todo message falls back to an empty state". Fixed by makingbuildTodoItemstotal: runtimetypeof/innarrowing instead of inline casts,Array.isArray(todos)guard, and a type-guard filter dropping null/primitive entries. Added malformed-shape unit tests (non-array object, primitive,[null, 42, valid], primitive metadata, missing metadata) at both thebuildTodoItemsandtodoListNotEmptyForSessionlevels (2 red → green). Committed as follow-upfix:.
Round-5 reviewer feedback (OMP GPT Luna) and disposition — all five fixed
- F1 (major): sessionless tasks bypass visibility sync —
useSyncTodoPanelearly-returned on!sessionId, so atodostab materialized from a saved layout on a task without a session could never be removed by the master preference. Fixed: the guard now requires onlytaskId/workspaceId/hasApi; a null session is treated as an empty todo list (never enables an add) while still allowing the removal path. - F2 (major): malformed todo metadata still crashed chat rendering —
TodoMessage's ownnormalizeTodos(non-arraytodos,[null]entries,previous_todo_snapshotsnon-array) threw, bypassing the round-4buildTodoItemshardening. Fixed:normalizeTodosis now total (unknown input,Array.isArray, type-guard filter dropping null/primitive/empty-text entries),parseTodos/parseSnapshotsnarrow viatypeof/ininstead of inline casts, and a newtodo-message.test.tsxpins all malformed shapes (5 tests, red → green). - F3 (major): delayed PATCH could clobber a newer WS settings update — the save callback unconditionally echoed the submission into the store; a WS push landing mid-flight would be reverted. Fixed: snapshot the store before the PATCH and only echo when it has not drifted; otherwise the server's own settings broadcast owns convergence. New component test with a deferred save + mid-flight store update (red → green).
- F4 (minor): empty-text entries counted as non-empty — the round-4
type-guard filter (
typeof item.text === "string") kept{ text: "" }, which the pre-fix code dropped; a blank entry could trigger pinning. Fixed: requireitem.text.length > 0inbuildTodoItems(and the mirroredTodoMessagefilter); regression tests at both levels. - F5 (minor): unbounded transcript scan when the sub-option is off — the
sync computed
buildTodoItems(O(n) copy+scan) on every message-array update even whenonlyPinWhenNotEmptyis false. Fixed: the predicate is only computed when the sub-option is on (and a session exists); otherwisefalseis passed (the decision ignores it).
Verification: 846 tests across the touched areas (chat, settings, sync,
processed-messages, SSR/WS) pass; pnpm run typecheck, make fmt, make lint clean; E2E todo-list-panel.spec.ts 8/8 (web rebuilt). Committed as
follow-up fix:.
Round-6 reviewer feedback (OMP GPT Luna) and disposition — all three fixed
- G1 (major): malformed snapshot entries still crashed TodoMessage —
parseSnapshotsvalidated array-ness but not entries, soprevious_todo_snapshots: [null]threw inSnapshotHistoryon expand. Fixed: entries are filtered to non-null objects; malformedsnapshot.todoswas already neutralized by the unknown-safenormalizeTodos. New tests click the "Earlier updates" toggle with[null, 42, valid]and malformed snapshottodos(red → green). - G2 (major): sessionless tasks could still receive an automatic Todos tab
— the round-5 fix enabled removal for null sessions but the add path still
fired when the sub-option was off (the resolver ignored the empty-list
predicate). Fixed:
resolveConditionalTodoPanelActiongained a requiredhasActiveSessionparam gating the add path; the hook passessessionId !== null. Removal for sessionless tasks is preserved. New decision-table rows (never-add, sessionless-remove, sessionless-keeps) and twosyncConditionalTodoPaneltests (red → green). - G3 (major): delayed save could leave the UI falsely clean and stale —
the round-5 drift guard skipped the store echo but still ran
setSaved(submitted), overwriting the newer WS hydration baseline soisDirtyflipped false against a stale submission. Fixed: on drift the save returns without touchingsaved, keeping the draft dirty against the newer baseline so the user can reconcile; the F3 test now asserts the dirty flag stays on (red → green).
Verification: 853 tests across the touched areas pass; pnpm run typecheck,
make fmt, make lint clean; E2E todo-list-panel.spec.ts 8/8 (web
rebuilt). Committed as follow-up fix:.
Round-9 reviewer feedback (OMP GPT Luna) and disposition
- J1 (major): full transcript scan on every message update while the
sub-option is on — analyzed, NOT fixed by the suggested incremental
tracker: a prototype tracker that only inspected the newest message after
a todo-free scan was demonstrated UNSOUND — when the first sync runs
before the messages fetch completes (
[]), then persisted history with a mid-arraytodomessage and a plain final message lands, the tracker returns false forever and the auto-pin for reopened completed tasks (a passing E2E scenario) breaks. A sound incremental version requires the messages store to expose todo-relevant derived state, which it does not (out of scope). The current behavior is already bounded: the predicate is computed only when the opt-in sub-option is on, and the livesessionTodosslice short-circuits the message scan while the session has live entries. Documented in the hook comment; the E2E persisted-history pin continues to pass. - J2 (minor): hook tests did not model rAF cancellation or frame
boundaries — FIXED: the hook-test harness now uses stable frame IDs
backed by a pending-callback map,
cancelAnimationFramedeletes the pending callback, and frames flush one at a time (outer schedules inner for the next flush). Added a between-frames test: a preference change after the outer frame cancels the pending inner, and exactly zero sync side effects fire for the stale state.
Verification: 862 tests across the touched areas pass; pnpm run typecheck,
make fmt, make lint clean; E2E todo-list-panel.spec.ts 8/8 (web
rebuilt). Committed as follow-up fix:/test:.
Blockers/risks: none.