[Task] Extract layout side-effect controllers from layout.tsx

[Astro-Han]

Goal

Reduce the risk of packages/app/src/pages/layout.tsx by extracting the first non-visual side-effect controller boundary into focused layout modules, without changing the visible shell, sidebar DOM, routing behavior, storage keys, copy, aria labels, or command IDs.

This is a narrow execution slice under the broader frontend debt governance work. It is not a user-facing feature request.

Scope

In scope:

• Extract update polling and SDK/desktop notification side effects from layout.tsx into focused modules or hooks under packages/app/src/pages/layout/.
• Keep the public Layout component responsible for shell composition and prop wiring.
• Preserve existing behavior for sidebar rows, session navigation, workspace switching, settings overlay, keyboard commands, and deep links.
• Add focused tests only when extraction creates pure decision logic worth testing directly.

Out of scope:

• No visual redesign.
• No PawworkSidebar component split.
• No TitleBar work.
• No workspace lifecycle extraction.
• No session window, prefetch, or navigation extraction.
• No behavior changes to notifications, updates, deep links, commands, or routing.

Relevant files or context

Likely files:

• packages/app/src/pages/layout.tsx
• packages/app/src/pages/layout/*
• packages/app/src/pages/layout/*.test.tsx
• packages/app/src/pages/layout/*.test.ts
• packages/app/e2e/sidebar*.spec.ts

Related issues:

• Refs [Task] Track frontend infrastructure debt outside UI rewrite #687
• Related to [Task] UI rewrite v2 Area E2: final shell modular rollout #606

Verification

• Run the app typecheck.
• Run targeted layout unit tests that cover the touched helpers/hooks.
• Run focused sidebar/layout E2E coverage if the extraction touches route, sidebar, command, or workspace wiring.
• Run a snap or manual shell check only if the visible rendered shell changes; this issue should avoid that.
• Confirm git diff does not include unrelated UI copy, DOM structure, data attributes, aria labels, command IDs, or storage key changes.

Execution mode

Investigate and propose a plan first. The split plan is posted as an issue comment; implementation should wait for explicit maintainer approval or assignment before opening a PR.

[Astro-Han]

Design note: layout.tsx split plan

Classification

This should stay a task, not an enhancement.

Reason: the work does not introduce a user-facing workflow or capability. It is a narrow, behavior-preserving maintainability slice. tech-debt is the right supplemental context because the value is future change safety and reviewability.

Current responsibilities

packages/app/src/pages/layout.tsx is currently doing several jobs at once:

• Shell composition: titlebar, sidebar, main outlet, settings overlay, debug panel, toast wiring, shell CSS variables.
• Route and project resolution: decoded route params, current directory, current project, active route sync.
• Sidebar/session model wiring: session windows, pinned state, sort order, hidden/collapsed projects, show-more behavior.
• Session navigation and prefetch: previous/next/unseen navigation, active-row scroll, message prefetch queue, cache eviction.
• Workspace lifecycle: open/close project, choose directory, create/delete/reset/rename workspaces, workspace order and expansion state.
• Global side effects: update polling, SDK event notifications, desktop notifications, permission sounds, worktree ready/failed handling, deep links, homepage migration.
• Command registration: command palette entries for sidebar, projects, sessions, workspaces, settings, theme, and language.

That mix makes the file expensive to read because visual shell decisions and background controller behavior are interleaved.

Split principle

Keep the visible shell stable first. Extract controller hooks that already have a natural boundary, a small input surface, and no JSX. Do not chase line count by splitting arbitrary helpers. Each PR should preserve behavior and be easy to revert.

The target is not "make every file under 200 lines at any cost". The target is: no file should be so broad that an agent must understand unrelated product areas to make a small change.

This issue's PR boundary

This issue should cover only the first non-visual side-effect slice:

1. Move the in-file useUpdatePolling hook into a focused module, for example packages/app/src/pages/layout/layout-update-polling.ts.
2. Move the in-file useSDKNotificationToasts hook into a focused SDK event-effects module, for example packages/app/src/pages/layout/layout-sdk-event-effects.ts.
3. Keep Layout responsible for calling these hooks and passing the already-owned dependencies.
4. Preserve all existing notification text keys, update actions, permission sound behavior, worktree ready/failed handling, dedupe rules, cooldown behavior, current/descendant checks, listener cleanup, interval cleanup, and route targets.

The extracted API should be boring and explicit. Use a named dependency object rather than a long positional parameter list. Group dependencies by purpose, for example:

• route: current params/current directory accessors and route builders.
• sdk: SDK event listener and synced session lookup.
• settings: reactive settings accessors, not eagerly-read setting values.
• effects: toast, desktop notification, sound, busy-state updates, and worktree state updates.
• copy: translation helpers.

The hook modules must preserve Solid owner semantics. Keep onMount, createEffect, and onCleanup inside the hook call path. Pass accessors/callbacks/dependency objects instead of plain snapshots for reactive values such as settings and current route state. Keep the notification Map/Set dedupe state inside the hook instance lifecycle, not at module scope.

Stop this PR before touching:

• PawworkSidebar JSX or visual row components.
• Session window, message prefetch, or scroll navigation controllers.
• Workspace lifecycle mutations beyond the existing worktree ready/failed event effects already inside this hook.
• Deep-link handling and homepage migration.
• Command palette registration.

Those are separate review surfaces.

Required lightweight verification layer

Because this slice extracts side effects, typecheck alone is not enough. The implementation PR should add at least one lightweight behavior guard:

• Preferred: extract pure decision helpers for current/descendant detection, question notification dedupe, permission cooldown, and cleanup keys, then cover them with focused unit tests.
• Acceptable: add event-driven hook tests that mount the hook in a Solid owner, emit SDK events, and assert listener cleanup, interval cleanup, notification calls, sound calls, dedupe/cooldown behavior, and worktree ready/failed updates.

Do not skip this layer unless the PR explicitly explains why the extraction stayed mechanically identical and lists the manual checks below.

Follow-up sequence

If this first slice lands cleanly, the next issues can be split like this:

1. Session navigation and prefetch controller: extract previous/next/unseen navigation, active session scroll, prefetch queue, and cache eviction behind a small route/session API.
2. Workspace lifecycle controller: extract create/delete/reset/rename workspace actions and related busy/error state behind a workspace action API.
3. Command registration controller: extract command palette assembly after the functions it calls have stable boundaries.
4. Deep-link and homepage migration controller: extract once project opening and pinned draft handoff are already easier to reason about.
5. Visual sidebar split: leave to a UI-capable pass, because it changes the component reading surface and may require visual verification beyond this controller cleanup.

Verification recipe

Minimum local verification for this issue:

• bun run typecheck
• cd packages/app && bun test --preload ./happydom.ts ./src/pages/layout/*.test.ts ./src/pages/layout/*.test.tsx
• Add or run focused tests for notification decision semantics: no duplicate question notification, no notification for the current session or a descendant of the current session, permission cooldown reset on permission.replied, question dedupe reset on terminal update or message.part.removed, and worktree ready/failed state updates.
• Manually review or test that update polling starts only when startup updates are enabled, stops when disabled, and clears its interval on cleanup.
• If route, sidebar, workspace, or command wiring changes despite the non-goal, add a focused E2E run such as cd packages/app && bun run test:e2e:local -- e2e/sidebar.spec.ts e2e/sidebar-session-links.spec.ts.
• If rendered shell output changes despite the non-goal, run an existing snap target such as bun run snap app-shell or the closest sidebar target and review the generated screenshot.

Review checklist

• layout.tsx delegates only the two side-effect hooks and does not gain new responsibilities.
• No UI copy, DOM structure, aria labels, data attributes, command IDs, route patterns, or storage keys change.
• Hook APIs use named dependency objects and preserve reactive accessors/callbacks rather than frozen values.
• onMount, createEffect, and onCleanup still run under the Layout owner's hook call path.
• Notification Map/Set state remains per hook instance, not module-global.
• SDK event listener unsubscribe and update polling interval cleanup are preserved.
• Notification dedupe and cooldown behavior are preserved.
• Current-session and descendant-session checks still suppress desktop notifications.
• Worktree ready/failed handling still updates busy state and WorktreeState exactly once per event.
• The PR is reversible as one controller extraction, not mixed with visual cleanup.

[Astro-Han]

Done in PR #877 (merged 2026-05-23): extracted update polling, SDK notification/permission/question/worktree event effects from layout.tsx into dedicated controller files.