@chanlerdev/scorel 0.0.1

package/docs/spec/ship/S0032-daemon-protocol-completion.md

@@ -0,0 +1,123 @@
+# S0032: Daemon Protocol Completion (Cancel, ListSessions, ListProjects)
+
+## Goal
+
+Restore and extend the daemon control protocol so M5 WebUI and CLI can:
+
+- cancel an in-progress turn from any client
+- list sessions scoped by `projectSlug`
+- list the projects this daemon has served
+
+The previous M5 attempt added `cancel` and partial `list_sessions`; both were rolled back in `4ebfabe`. This spec re-introduces them on top of S0031's daemon-owned `projectSlug`, plus a new `list_projects` request that exposes the daemon's project view to clients.
+
+## Scope
+
+- `@scorel/protocol`:
+  - Re-add `cancel` request:
+    ```ts
+    cancel: {
+      request: { sessionId: SessionId };
+      response: { sessionId: SessionId; cancelled: boolean };
+    };
+    ```
+  - Restore real `list_sessions` shape and add `projectSlug` filter:
+    ```ts
+    list_sessions: {
+      request: { projectSlug?: string; limit?: number };
+      response: { sessions: SessionSummary[] };
+    };
+    ```
+  - Extend `SessionSummary` with `projectSlug: string` so callers can group across daemons.
+  - New `list_projects` request:
+    ```ts
+    list_projects: {
+      request: Record<never, never>;
+      response: { projects: DaemonProjectSummary[] };
+    };
+
+    type DaemonProjectSummary = {
+      projectSlug: string;
+      displayName: string;        // basename(workDir)
+      workDirHint?: string;       // absolute path daemon last saw
+      sessionCount: number;
+      lastSeenAt: number;         // max(updatedAt) over the project's sessions
+    };
+    ```
+- `@scorel/daemon`:
+  - Re-implement `#handleCancel` (logic identical to the rolled-back version).
+  - Implement `list_sessions`:
+    - source: in-memory session lanes plus on-disk `<sessionsDir>/*.jsonl` headers (lazy scan, same dir layout as today)
+    - apply `projectSlug` filter when present
+    - respect `limit` (default 200, max 1000)
+    - sort by `updatedAt` desc, then `sessionId` asc for stability
+    - return `currentSeq` from in-memory lane when loaded, else from JSONL header tail
+  - Implement `list_projects`:
+    - aggregate sessions in `<sessionsDir>/` by reading their headers (cwd in `meta` if present; else fall back to `toProjectSlug(daemon.workDir)`)
+    - cache the scan in-memory; invalidate when a new session is created or appended
+    - return all projects daemon has touched, even if every session is stale
+  - Persist a session header field that pins the slug at session creation time so list_projects/list_sessions stay deterministic across daemon restarts (extend `SessionMeta` with `projectSlug?: string`; daemon writes it; readers prefer the header field).
+- `@scorel/client`:
+  - Re-add `DaemonClient.cancel()`.
+  - Add `DaemonClient.listSessions(filter?: { projectSlug?: string; limit?: number })`.
+  - Add `DaemonClient.listProjects()`.
+  - All three thin wrappers around the request/response wire; no business logic.
+- `apps/cli`:
+  - CLI `chat` and `attach` keep working unchanged. CLI does not need to call `list_projects` in this spec; `cancel` and `list_sessions` are wired only when CLI features already use them (cancel-on-Ctrl-C exists today and was rolled back too — restore call site).
+  - `scorel attach --remote` continues to populate the project-index file via `list_sessions` results (reuses the new shape).
+
+## Not In Scope
+
+- WebUI consumption (M5.4+).
+- Project-index v2 / cross-device aggregation.
+- Daemon-side session creation API (`create_session` already exists; not changed here).
+- Permission gates / auth scopes around `cancel` (single-user model only).
+- Pagination / cursors for `list_sessions` beyond `limit`.
+
+## Acceptance Criteria
+
+- Wire schema: `cancel`, `list_sessions`, `list_projects` are present in `packages/protocol/src/wire.ts` exactly as above; round-trip tests in `packages/protocol/src/index.test.ts` cover each.
+- `EmbeddedDaemon`:
+  - `cancel` returns `{ sessionId, cancelled: bool }` and writes a `cancel_requested` diagnostic; cancellation actually interrupts a running runtime turn (re-establish the rolled-back behavior, no regressions).
+  - `list_sessions({ projectSlug })` returns only sessions matching the slug; `list_sessions()` returns all known sessions; `limit` clamps result size.
+  - `list_projects()` returns one entry per distinct slug seen across sessions, with correct `sessionCount`, `lastSeenAt`, and `displayName`.
+  - Session JSONL header includes `projectSlug` for new sessions; reading older sessions without that field falls back to `toProjectSlug(daemon.workDir)`.
+- `DaemonClient` exposes `cancel()`, `listSessions()`, `listProjects()`. Cancel and listSessions throw if not connected to a session / daemon respectively; listProjects only requires daemon connection (no session).
+- CLI Ctrl-C path triggers `cancel()` on the active session and prints a cancellation marker (restore prior behavior).
+- `pnpm typecheck && pnpm test` passes.
+- Manual real-daemon validation:
+  - Run `scorel chat`, send a long-running tool prompt, Ctrl-C → daemon emits cancel, CLI shows cancelled.
+  - Run two `scorel chat` sessions in different `--cwd` directories; a third client calling `listProjects()` returns both slugs with correct counts.
+
+## Tests
+
+- Protocol round-trip: every new message shape encodes/decodes via existing schema validators.
+- Daemon unit tests for `list_sessions` filtering, sorting, limit clamping; `list_projects` aggregation across mixed in-memory and on-disk sessions; `cancel` happy path and "no running turn" path.
+- DaemonClient unit tests for the three new methods (request id correlation, session-id requirement for cancel, error response handling).
+- CLI test re-asserts Ctrl-C → cancel diagnostic.
+- Manual: see Acceptance Criteria.
+- Run targeted tests then `pnpm typecheck && pnpm test`.
+
+## Affected Paths
+
+- `packages/protocol/src/wire.ts`
+- `packages/protocol/src/events.ts` (extend `SessionSummary` with `projectSlug`; add `DaemonProjectSummary` if it lives here, else add new `projects.ts` module — choose `events.ts` to avoid file proliferation)
+- `packages/protocol/src/index.test.ts`
+- `packages/daemon/src/index.ts`
+- `packages/daemon/src/index.test.ts` (or new `protocol.test.ts` reintroduced)
+- `packages/daemon/src/projects/aggregator.ts` (new — reads JSONL headers and aggregates by slug)
+- `packages/daemon/src/projects/aggregator.test.ts` (new)
+- `packages/client/src/index.ts`
+- `packages/client/src/daemon-client.test.ts` (reintroduce, scoped to new methods)
+- `apps/cli/src/index.ts`
+- `apps/cli/src/index.test.ts`
+- `docs/spec/daemon.md`
+- `docs/spec/client.md`
+- `docs/ROADMAP.md` (M5 step entry for S0032)
+
+## Risks And Boundaries
+
+- Reading every JSONL header on `list_projects` / `list_sessions` is O(N) over disk; acceptable for v1 (single-user, dozens to hundreds of sessions). Add an in-memory cache invalidated on session create/append so steady-state cost is constant.
+- `projectSlug` collision (S0031 documented `-` ambiguity) means `list_projects` cannot reverse a slug back to a unique `workDir`; clients display `displayName` and `workDirHint` from the daemon and never reverse-engineer.
+- Cancellation already had a rolled-back implementation in git history. Re-introduce that exact behavior; do not invent new semantics.
+- `SessionMeta.projectSlug?` is additive; existing sessions without it remain readable (fallback path covered above).
+- `list_projects` exposes daemon's full session map. Acceptable in single-user model; if multi-tenant ever lands, gating is a future spec.

package/docs/spec/ship/S0033-webui-skeleton-routing.md

@@ -0,0 +1,92 @@
+# S0033: WebUI Application Skeleton And Routing
+
+## Goal
+
+Stand up `apps/webui` as a Next.js 14 App Router project with Tailwind 4, wire it into the pnpm monorepo, and lock the URL routing surface for the rest of M5. No real data, no daemon connection — just a deployable empty shell with the right shape.
+
+This spec exists separately from M5.4+ because the previous M5 attempt lumped framework integration with feature work, which hid build/ESM regressions inside feature commits. This time the skeleton lands first, alone.
+
+## Scope
+
+- New app `apps/webui`:
+  - `package.json` with `next@14`, `react@18`, `react-dom@18`, `tailwindcss@4`, `@scorel/protocol` (workspace), `@scorel/client` (workspace).
+  - `tsconfig.json` extending the repo TS base config.
+  - `next.config.mjs` with `transpilePackages: ["@scorel/protocol", "@scorel/client"]` so monorepo TS sources work without prebuild.
+  - Tailwind v4 wired through PostCSS (`postcss.config.mjs`) and global stylesheet.
+- App Router shell:
+  - `app/layout.tsx` — global HTML / body / Tailwind reset; renders sidebar slot + main slot.
+  - `app/page.tsx` — root empty state ("Add a Device in Settings to start").
+  - `app/devices/[deviceId]/page.tsx` — per-device empty state.
+  - `app/devices/[deviceId]/projects/[projectSlug]/page.tsx` — per-project empty state.
+  - `app/devices/[deviceId]/projects/[projectSlug]/sessions/[sessionId]/page.tsx` — chatbox empty state.
+  - `app/settings/page.tsx` — settings root empty.
+  - `app/settings/devices/[deviceId]/page.tsx` — device edit empty.
+- Sidebar / topbar component scaffolds:
+  - `components/shell/sidebar.tsx` — hardcoded layout with `New Chat` action, empty Projects tree, bottom Settings link. No real data wiring.
+  - `components/shell/topbar.tsx` — selected device label + connection placeholder.
+  - All components are server-rendered or `"use client"` only when strictly needed.
+- Build/dev scripts:
+  - `pnpm --filter @scorel/webui dev` runs `next dev`.
+  - `pnpm --filter @scorel/webui build` runs `next build`.
+  - `pnpm --filter @scorel/webui typecheck` runs `tsc --noEmit -p tsconfig.json`.
+  - `pnpm --filter @scorel/webui test` runs `vitest --run`. With zero tests v1, the script must still exit 0.
+- Lint/format: lean on existing repo config; do not introduce ESLint per-app unless required by Next 14 to build.
+- Repo-level `pnpm typecheck && pnpm test` continues to pass with the new app included.
+
+## Not In Scope
+
+- Device CRUD, BrowserStore, DaemonClient instantiation, real sidebar tree, chatbox, settings forms (M5.4–M5.9).
+- UI library beyond Tailwind primitives (no Radix / Base UI / shadcn integration in this spec).
+- Auth, theming, dark mode, i18n.
+- Service worker / PWA / SSR optimization.
+- Static export (`next export`); spec assumes `next dev` / `next build` against Node 22.
+
+## Acceptance Criteria
+
+- `pnpm install` succeeds with no warnings about peer deps Scorel can fix.
+- `pnpm --filter @scorel/webui build` succeeds; output has the seven routes above.
+- `pnpm --filter @scorel/webui dev` boots and serves all seven routes returning 200 with a recognizable empty-state string.
+- `pnpm --filter @scorel/webui typecheck` succeeds.
+- Top-level `pnpm typecheck && pnpm test` succeeds.
+- `apps/webui/src` only imports from `@scorel/protocol` and `@scorel/client` (and Next/React/Tailwind). No imports from `@scorel/core` or Node-only paths. Enforced by a focused vitest spec or eslint rule (vitest is fine for v1).
+- Routing matches §Scope exactly; URL params are accepted as plain strings (no decoding logic yet).
+- Tailwind classes render (smoke: visit any route, body has Tailwind preflight applied).
+
+## Tests
+
+- Add `apps/webui/src/package-boundaries.test.ts` (Vitest) verifying the imports rule above by parsing TS files via `node:fs` and a simple regex over `from "..."` strings.
+- Add `apps/webui/src/routes.test.ts` enumerating the seven route segments from `app/` directory listing and asserting they match the expected set.
+- Run `pnpm --filter @scorel/webui typecheck && pnpm --filter @scorel/webui test`.
+- Run `pnpm typecheck && pnpm test` at repo root.
+- Manual: `pnpm --filter @scorel/webui dev`; visit each route; confirm empty state text.
+
+## Affected Paths
+
+- `apps/webui/package.json` (new)
+- `apps/webui/tsconfig.json` (new)
+- `apps/webui/next.config.mjs` (new)
+- `apps/webui/postcss.config.mjs` (new)
+- `apps/webui/tailwind.config.ts` (new — even though Tailwind 4 supports zero-config, pin content paths explicitly)
+- `apps/webui/app/layout.tsx`
+- `apps/webui/app/globals.css`
+- `apps/webui/app/page.tsx`
+- `apps/webui/app/devices/[deviceId]/page.tsx`
+- `apps/webui/app/devices/[deviceId]/projects/[projectSlug]/page.tsx`
+- `apps/webui/app/devices/[deviceId]/projects/[projectSlug]/sessions/[sessionId]/page.tsx`
+- `apps/webui/app/settings/page.tsx`
+- `apps/webui/app/settings/devices/[deviceId]/page.tsx`
+- `apps/webui/components/shell/sidebar.tsx`
+- `apps/webui/components/shell/topbar.tsx`
+- `apps/webui/src/package-boundaries.test.ts`
+- `apps/webui/src/routes.test.ts`
+- `pnpm-lock.yaml`
+- `docs/architecture.md` (note WebUI app exists)
+- `docs/ROADMAP.md` (M5 step entry for S0033)
+
+## Risks And Boundaries
+
+- **ESM in monorepo with Next**: Next 14 handles workspace TS via `transpilePackages`. If `@scorel/client` ships dual ESM/CJS later, this list must include both. Spec keeps `transpilePackages` and avoids introducing build steps for protocol/client.
+- **Tailwind 4** is current at the time of writing; if API drift forces Tailwind 3, swap before merge — do not block M5 on Tailwind 4 specifics. *Implementation note (2026-05-31)*: Tailwind 4.3.0 stable + `@tailwindcss/postcss` 4.3.0 installed cleanly with Next 14.2.35; no fallback to Tailwind 3 was needed.
+- **App Router strictness**: server components are default; any state hook needs `"use client"`. Skeleton stays mostly server-rendered.
+- **Bundle size** is irrelevant v1; we run `next dev` locally and `next build` for verification, not production deploy.
+- Do not pull in extra UI libs until S0034 actually needs them; this spec stays minimal so feature commits don't fight framework decisions.

package/docs/spec/ship/S0034-webui-device-settings.md

@@ -0,0 +1,121 @@
+# S0034: WebUI Device Model And Settings CRUD
+
+## Goal
+
+Lock the WebUI domain model (`Device`, `DeviceProject`, `DeviceSessionSummary`), introduce the single browser-storage abstraction (`BrowserStore`, `localStorage` v1), and ship the Settings page so users can add / edit / delete a Device. No daemon connection yet — Settings is purely local persistence.
+
+## Scope
+
+- Domain types in `apps/webui/lib/domain/devices.ts`:
+  ```ts
+  type Device = {
+    id: string;                  // ulid generated client-side
+    name: string;
+    link: string;                // normalized wss://host[:port][/path] | ws://...
+    token: string;               // v1 cleartext
+    createdAt: number;
+    lastConnectedAt?: number;
+    remoteIdentity?: { deviceId: string; deviceDisplayName?: string };
+    projects?: DeviceProject[];
+    projectsFetchedAt?: number;
+  };
+  type DeviceProject = {
+    projectSlug: string;
+    displayName?: string;
+    workDirHint?: string;
+    sessionCount?: number;
+    lastSeenAt?: number;
+    sessions?: Record<string, DeviceSessionSummary>;
+    sessionsFetchedAt?: number;
+  };
+  type DeviceSessionSummary = {
+    sessionId: string;
+    title?: string;
+    model?: string;
+    updatedAt?: number;
+    currentSeq?: number;
+  };
+  ```
+- BrowserStore abstraction in `apps/webui/lib/store/browser-store.ts`:
+  - Single namespace prefix: `scorel:webui:v1:`.
+  - API: `get<T>(key): T | undefined`, `set<T>(key, value): void`, `remove(key): void`, `subscribe(key, listener): unsubscribe` (uses `storage` events for cross-tab + an in-process pub/sub).
+  - Quota handling: catch `QuotaExceededError`; expose `onQuotaExceeded` hook (used by future attach-cache evictor; v1 just logs and rethrows).
+  - SSR safety: `BrowserStore` constructor takes `storage: Storage | null`. On the server (Next.js render), pass `null` and all reads return `undefined`, all writes are no-ops. Hooks integrate with `useSyncExternalStore`.
+- Devices store in `apps/webui/lib/store/devices.ts`:
+  - Reads/writes `scorel:webui:v1:devices` (a JSON-encoded `Device[]`).
+  - Methods: `list()`, `get(id)`, `create(input)`, `update(id, patch)`, `remove(id)`. All synchronous on top of BrowserStore.
+  - `create` generates ulid via `crypto.randomUUID` (acceptable v1; ulid lib only if string format matters).
+  - Validates and normalizes Link before persist (see below).
+- Link normalization in `apps/webui/lib/domain/link.ts`:
+  - Accept input: `wss://host[:port][/path]` or `ws://host[:port][/path]`. Reject anything else with a clear error string.
+  - Trim whitespace.
+  - Lowercase scheme and host.
+  - Strip trailing `/`.
+  - Reject empty token (separate validator on the form).
+- Settings UI in `apps/webui/app/settings/page.tsx` and `apps/webui/app/settings/devices/[deviceId]/page.tsx`:
+  - List page: table/list of devices, "Add Device" button, edit + delete actions.
+  - Add/edit form fields: Name (required, 1–64 chars), Link (required, validated by `link.ts`), Token (required, 1–4096 chars; rendered as password input).
+  - Form errors shown inline; submit disabled while invalid.
+  - Delete confirms via standard browser `confirm()`; v1 acceptable.
+- Sidebar wiring in `apps/webui/components/shell/sidebar.tsx`:
+  - Read devices via the devices store hook.
+  - Render Device nodes (just name + faint "not connected" badge — connection happens in S0035).
+  - Each Device node links to `/devices/:deviceId`.
+- Empty-state copy: when no devices exist, root page shows "Add a device in Settings to get started" with a button linking to `/settings`.
+
+## Not In Scope
+
+- DaemonClient instantiation, handshake, project/session listing (S0035, S0036).
+- Connection state indicators beyond "configured but not connected" placeholder.
+- Token encryption / Web Crypto / IndexedDB.
+- Multi-tab realtime sync of device list (basic `storage` event subscription is included; no conflict resolution beyond last-write-wins).
+- Import / export devices.
+- Dark mode / theming.
+
+## Acceptance Criteria
+
+- Domain types match §Scope exactly; exported from `lib/domain/devices.ts`.
+- BrowserStore is the only module that touches `localStorage` directly. Enforced by the package-boundaries test from S0033 extended to forbid `localStorage` references outside `lib/store/`.
+- Devices store round-trips: create → list returns the device; update mutates fields; remove deletes. All reflected in `localStorage` under `scorel:webui:v1:devices`.
+- Link validator rejects: `http://...`, `https://...`, `wss:`/`wss:///`, empty, plain hostname. Accepts `wss://host`, `wss://host:9876`, `ws://localhost:8765`, `wss://host/path/`.
+- Settings list page renders all devices; add form creates a new device; edit form updates; delete removes.
+- Sidebar shows configured devices with "not connected" badge; clicking navigates to `/devices/:deviceId`.
+- Root empty state appears when zero devices configured.
+- `pnpm --filter @scorel/webui typecheck && pnpm --filter @scorel/webui test` passes.
+- Manual: open `/settings`, add a device with link `wss://localhost:9876` and token `abc`, verify list shows it; refresh page, device persists; edit name; delete; confirm sidebar reflects changes live.
+
+## Tests
+
+- Unit tests for `lib/domain/link.ts` covering accept/reject cases.
+- Unit tests for `lib/store/devices.ts` using `vitest` with a fake `Storage` implementation.
+- Unit test extending `package-boundaries.test.ts` to assert `localStorage` only appears under `lib/store/`.
+- Component test (Vitest + jsdom) for settings list and add form: rendering, form validation error states, submit dispatch.
+- Run `pnpm --filter @scorel/webui typecheck && pnpm --filter @scorel/webui test`.
+- Run repo-level `pnpm typecheck && pnpm test`.
+
+## Affected Paths
+
+- `apps/webui/lib/domain/devices.ts` (new)
+- `apps/webui/lib/domain/link.ts` (new)
+- `apps/webui/lib/domain/link.test.ts` (new)
+- `apps/webui/lib/store/browser-store.ts` (new)
+- `apps/webui/lib/store/browser-store.test.ts` (new)
+- `apps/webui/lib/store/devices.ts` (new)
+- `apps/webui/lib/store/devices.test.ts` (new)
+- `apps/webui/app/settings/page.tsx`
+- `apps/webui/app/settings/devices/[deviceId]/page.tsx`
+- `apps/webui/components/settings/device-list.tsx` (new)
+- `apps/webui/components/settings/device-form.tsx` (new)
+- `apps/webui/components/shell/sidebar.tsx`
+- `apps/webui/app/page.tsx` (empty-state with link to settings)
+- `apps/webui/src/package-boundaries.test.ts` (extend)
+- `docs/ROADMAP.md` (M5 step entry for S0034)
+
+## Risks And Boundaries
+
+- **Token cleartext**: documented v1 trade-off; spec must not promise encryption later in this milestone. README/UX should warn users not to share screenshots of Settings.
+- **`crypto.randomUUID`** is available in modern browsers; pin to it (no polyfill).
+- **SSR**: Settings forms are client components (`"use client"`); the rest of the shell stays server-rendered where possible.
+- **Cross-tab races**: last-write-wins via `storage` event is acceptable v1; document the gap.
+- **Form library**: keep it native (`<form>` + `useState`). No react-hook-form / zod runtime in this spec; if S0035+ need stronger validation, reassess then.
+- **Quota**: with only the Devices array v1 we are far below 5MB; explicit quota handling lives in attach-cache work (S0037+).

package/docs/spec/ship/S0035-webui-device-handshake.md

@@ -0,0 +1,83 @@
+# S0035: WebUI Device Connection Handshake
+
+## Goal
+
+Wire the configured `Device` list to real `DaemonClient + WsTransport` connections. After this spec, opening a Device in the sidebar establishes a WebSocket connection, the daemon's identity (`deviceId`, `deviceDisplayName`) is captured into `Device.remoteIdentity`, and connection status is visible. No project/session listing yet.
+
+## Scope
+
+- Connection pool in `apps/webui/lib/connection/pool.ts`:
+  - Owns one `DaemonClient` instance per `Device.id`.
+  - Lazily creates a client when the user navigates to `/devices/:deviceId` (or descendants).
+  - Methods: `acquire(deviceId): ManagedConnection | undefined`, `release(deviceId)`, `subscribe(deviceId, listener)`.
+  - Uses `WsTransport` from `@scorel/client` with `link` and `token` from the device record.
+  - Reuses an existing client if present and not in `error`/`disconnected` terminal state.
+- Connection state machine in `apps/webui/lib/connection/state.ts`:
+  - States: `idle` → `connecting` → `connected` → (`reconnecting` | `disconnected` | `error`).
+  - Transitions driven by `DaemonClient` callbacks (`onConnected`, `onDisconnect`, `onError` if present; otherwise wrap `connect()` promise + `state` getter from the existing client API).
+  - `error` carries a categorized reason: `auth | network | version_mismatch | unknown`. Categorization rules:
+    - `auth` ↔ daemon error code `auth_failed` / HTTP 401-equivalent close codes.
+    - `network` ↔ ws close code 1006 / DNS / TCP errors.
+    - `version_mismatch` ↔ daemon `protocolVersion` field disagreement.
+    - else `unknown`.
+- Identity capture:
+  - On successful handshake (`connected` daemon message), update `Device.remoteIdentity = { deviceId, deviceDisplayName }` via the devices store; also update `Device.lastConnectedAt`.
+  - The handshake-supplied `defaultProjectSlug` (if any from S0032) is ignored here — projects are populated in S0036.
+- UI:
+  - `components/shell/sidebar.tsx` Device node shows live status: dot color + tooltip text matching the state machine state.
+  - `app/devices/[deviceId]/page.tsx` shows a "Connecting…" / "Connected as <displayName>" / "Error: <reason>" banner.
+  - "Reconnect" button on error/disconnected; "Disconnect" on connected (manual disconnect transitions to `idle`).
+  - Switching device in the sidebar does not eagerly connect every other device; only the current route's device is acquired. Other devices stay `idle` unless previously connected (then keep their already-open ws). Lifetime: when the user navigates away from a device for more than 60 seconds, release its connection. (Make this delay a constant for now; adjust later.)
+- Errors:
+  - Auth failure: show "Token rejected; update token in Settings". Link to `/settings/devices/:deviceId`.
+  - Network failure: show "Cannot reach <host>; will retry". Pool retries with exponential backoff: 1s, 2s, 4s, 8s, capped at 30s; retries stop after 5 consecutive network failures and stays `disconnected` until user clicks Reconnect.
+  - Version mismatch: show "Daemon protocol version unsupported; upgrade required". No retry.
+
+## Not In Scope
+
+- `list_projects` / `list_sessions` calls (S0036).
+- Session attach / event stream (S0037).
+- Background reconnect when WebUI tab is hidden (browser may freeze ws; rely on user interaction to retrigger).
+- Multi-tab connection coordination (each tab is independent v1).
+- Token rotation, refresh, OAuth.
+
+## Acceptance Criteria
+
+- Connection pool creates exactly one client per device id; concurrent route navigations don't spawn duplicates.
+- State machine transitions match the table in §Scope; verified by unit tests with a fake `DaemonClient`.
+- After handshake, `Device.remoteIdentity` and `lastConnectedAt` are persisted and visible in `/settings/devices/:deviceId`.
+- Sidebar status dot reflects live state (use `useSyncExternalStore` against the pool's per-device subscription).
+- Error categorization unit tests cover each reason path.
+- Manual: start a real daemon (`scorel daemon serve --remote`), add the device in WebUI, verify sidebar dot turns green; stop daemon → red with retry; restart daemon → re-clicking Reconnect transitions to green.
+- `pnpm --filter @scorel/webui typecheck && pnpm --filter @scorel/webui test` passes.
+- Repo `pnpm typecheck && pnpm test` passes.
+
+## Tests
+
+- Unit tests for connection state machine: every legal transition, illegal transitions are rejected.
+- Pool tests: lazy create, reuse, release after timeout, no duplicate clients across rapid navigations.
+- Error categorization tests for the four reason buckets.
+- Component test for sidebar Device node states.
+- Manual real-daemon validation per Acceptance Criteria.
+
+## Affected Paths
+
+- `apps/webui/lib/connection/pool.ts` (new)
+- `apps/webui/lib/connection/pool.test.ts` (new)
+- `apps/webui/lib/connection/state.ts` (new)
+- `apps/webui/lib/connection/state.test.ts` (new)
+- `apps/webui/lib/connection/error.ts` (new — categorization)
+- `apps/webui/lib/connection/error.test.ts` (new)
+- `apps/webui/components/shell/sidebar.tsx` (live status)
+- `apps/webui/components/shell/device-status.tsx` (new)
+- `apps/webui/app/devices/[deviceId]/page.tsx` (banner + reconnect/disconnect)
+- `apps/webui/lib/store/devices.ts` (add `markIdentity`, `markConnectedAt` helpers if needed)
+- `docs/ROADMAP.md` (M5 step entry for S0035)
+
+## Risks And Boundaries
+
+- `DaemonClient` API surface for connection events may not currently include all hooks needed; if so, extend `@scorel/client` minimally — keep that change in this spec, and document it in `docs/spec/client.md`.
+- Browser WebSocket has limited error introspection. Categorization is best-effort; document the unreliability.
+- Backoff constants (1s/2s/4s/8s/30s, 5 attempts) are tuned by feel; expose them as constants for easy adjustment but do not make them user-configurable v1.
+- Holding open ws for inactive devices wastes daemon connections. The 60-second release rule is a v1 compromise; revisit if user feedback says it churns too aggressively.
+- Multi-tab same-device duplicate connections are accepted v1; daemon already supports multiple clients per session.

package/docs/spec/ship/S0036-webui-project-session-sync.md

@@ -0,0 +1,70 @@
+# S0036: WebUI Project And Session Sync
+
+## Goal
+
+After a device is connected, populate its project list via `list_projects` and (lazily) its session list per project via `list_sessions({ projectSlug })`. Render the sidebar tree (Device → Project → Session) from the persisted `Device.projects` snapshot, with offline-cache fallback.
+
+## Scope
+
+- After handshake (state machine reaches `connected`), `lib/connection/sync.ts` calls `client.listProjects()` and writes the result into `Device.projects` via the devices store. Stale `projects` from a prior connection are replaced wholesale (overwrite snapshot, not merge).
+- Sidebar Device node renders `Device.projects` if present, else "(no projects yet)" placeholder. Connected and `projects` empty → render same placeholder; offline → render last persisted `projects` with a faint "offline" tint.
+- Selecting a project (clicking Project node, or navigating to `/devices/:deviceId/projects/:projectSlug`) triggers `client.listSessions({ projectSlug, limit: 200 })`. Result writes to `DeviceProject.sessions` (keyed by `sessionId`) and updates `sessionsFetchedAt`.
+- Sessions list renders newest first by `updatedAt`. If `sessions` already cached, render immediately and refresh in background; replace on refresh result.
+- New project navigation uses Next.js `Link` and updates URL state via App Router. Sidebar reflects the active route.
+- Sync helpers in `apps/webui/lib/sync/projects.ts` and `apps/webui/lib/sync/sessions.ts`:
+  - `syncProjects(deviceId)`: client.listProjects → store.update.
+  - `syncSessions(deviceId, projectSlug)`: client.listSessions → store.update.
+  - Both deduplicate concurrent calls per (deviceId, projectSlug).
+- Empty / error paths:
+  - listProjects fails: keep existing `Device.projects` cache; show toast/banner "Failed to load projects" with retry button.
+  - listSessions fails: same pattern at the project level.
+- URL params: `projectSlug` may contain unreserved characters per S0031 (no `/`, no encoding tricks needed). Use `decodeURIComponent` defensively when reading from `params` — but daemon-emitted slugs already pass through Tailwind/URL path safely.
+
+## Not In Scope
+
+- Chatbox (S0037) — selecting a session shows an empty chatbox shell with header info only here.
+- attach-cache reads (those land in S0037 alongside dual-seq resync).
+- Cross-device project aggregation / search.
+- Session creation (`New Chat`) — lives in S0039.
+- Real-time push of new sessions / projects (no server-side push API yet; v1 polls on user navigation).
+
+## Acceptance Criteria
+
+- After connecting a device with three projects, sidebar shows three Project nodes under that Device with daemon-supplied `displayName`.
+- Clicking a Project node lists its sessions; sessions persisted to `DeviceProject.sessions` so re-navigating after reload shows the cached list before the refresh fetch resolves.
+- Disconnecting the device transitions sidebar to faint "offline" tint but keeps the last project/session structure visible until the user removes the device.
+- Project list refresh on every successful (re)connect (overwrite); session list refresh on every project navigation; both deduplicated under concurrent triggers.
+- listProjects / listSessions errors do not erase cache; they show a non-blocking error banner.
+- `pnpm --filter @scorel/webui typecheck && pnpm --filter @scorel/webui test` passes.
+- Repo `pnpm typecheck && pnpm test` passes.
+- Manual: with two real daemons (different `--cwd`), each registered as a Device, sidebar shows both Devices with their respective projects.
+
+## Tests
+
+- Unit tests for `syncProjects` / `syncSessions` happy path, error preservation, concurrent dedupe.
+- Component tests for sidebar Project / Session nodes (rendered from a fake store).
+- Integration test using a stub `DaemonClient` returning canned `listProjects` / `listSessions` results, asserting store mutation and URL navigation behavior.
+- Manual: as above.
+
+## Affected Paths
+
+- `apps/webui/lib/sync/projects.ts` (new)
+- `apps/webui/lib/sync/projects.test.ts` (new)
+- `apps/webui/lib/sync/sessions.ts` (new)
+- `apps/webui/lib/sync/sessions.test.ts` (new)
+- `apps/webui/lib/store/devices.ts` (add `setProjects`, `setProjectSessions` helpers)
+- `apps/webui/components/shell/sidebar.tsx` (project + session nodes)
+- `apps/webui/components/shell/project-node.tsx` (new)
+- `apps/webui/components/shell/session-node.tsx` (new)
+- `apps/webui/app/devices/[deviceId]/page.tsx` (kick off `syncProjects` on mount via `"use client"` effect)
+- `apps/webui/app/devices/[deviceId]/projects/[projectSlug]/page.tsx` (kick off `syncSessions`)
+- `apps/webui/app/devices/[deviceId]/projects/[projectSlug]/sessions/[sessionId]/page.tsx` (placeholder chatbox header; full chatbox in S0037)
+- `docs/ROADMAP.md` (M5 step entry for S0036)
+
+## Risks And Boundaries
+
+- `list_sessions` returns up to 200 entries v1 (per S0032 default). For projects with thousands of sessions, the sidebar truncates silently. Acceptable v1; flag as a known limit.
+- Cache eviction: device removal must clean up its `projects` entries (handled in S0034 store helpers; verify here).
+- Navigating to a session under a project not yet synced is allowed (URL deep-linking); the page still triggers `syncSessions` even if the session isn't in cache yet — chatbox itself can attach by `sessionId` regardless.
+- Cross-tab freshness: when one tab fetches, other tabs receive the update via `storage` event (BrowserStore subscription). Acceptable v1; may flicker if both tabs fetch simultaneously.
+- No optimistic creation here. All sidebar items reflect daemon truth after handshake.

package/docs/spec/ship/S0037-webui-chatbox-v1.md

@@ -0,0 +1,97 @@
+# S0037: WebUI Chatbox v1
+
+## Goal
+
+Open a session and see a working chatbox: history rendered from attach-cache (instant), reconciled with daemon via dual-seq resync, live event stream (user / assistant / streaming delta / tool call / tool result) projected to UI, and a composer that sends prompts. No `cancel` (S0038) and no `New Chat` (S0039) yet.
+
+## Scope
+
+- Session attach in `apps/webui/lib/connection/session.ts`:
+  - On chatbox mount, take the device's `DaemonClient`, call `connect({ sessionId, persistentLastSeq, streamLastSeq })` using anchors from attach-cache.
+  - Subscribe to `event` messages and feed them to the projector.
+  - On unmount or session change, unsubscribe but keep the underlying client connection (pool-managed).
+- Attach-cache in `apps/webui/lib/store/attach-cache.ts`:
+  - Key: `scorel:webui:v1:attach-cache:<scopeKey>:<sessionId>`. `scopeKey = sha256(kind\0locator).hex.slice(0,24)`; for WebUI always `kind="remote"`, `locator="device:<remoteDeviceId>/project:<projectSlug>"`.
+  - `scopeKey` computed via Web Crypto SubtleCrypto in browser (async); cache the result per (deviceId, projectSlug, sessionId) tuple in memory.
+  - File shape: `{ version: 1, scope, sessionId, events: PersistentEvent[], transients?: { eventId, seq, text }[] }` (mirrors CLI `AttachCacheFile`).
+  - Append on every received persistent event; truncate transients on `turn_end`.
+  - Quota fallback: if `setItem` throws QuotaExceeded, drop oldest transients first, then evict the least-recently-used non-current session's cache.
+- Event projector in `apps/webui/lib/events/projector.ts`:
+  - Reduce `(state, event)` into a list of UI turns: `[{ id, kind: "user" | "assistant" | "tool", parts: TurnPart[] }]`.
+  - Streaming delta merges into the in-flight assistant turn keyed by `assistantEventId` from `message_start`.
+  - Tool calls and tool results group under their assistant turn.
+  - Final `assistant_message` event replaces the streamed assistant turn (deduplicate via id).
+  - Skip events whose `seq` is already incorporated.
+- Chatbox UI in `app/devices/[deviceId]/projects/[projectSlug]/sessions/[sessionId]/page.tsx` (client component):
+  - Header: session title, model, last updated.
+  - Transcript: scrollable, autoscroll-on-new-event when scrolled to bottom; preserve position otherwise.
+  - Turn renderers: user (markdown-light, plain text initially fine), assistant (streaming-aware), tool call (collapsible JSON), tool result (collapsible).
+  - Composer: textarea + Send button; `Enter` submits, `Shift+Enter` newline. Empty submit ignored. `Send` calls `client.sendMessage(content)`; optimistic local user turn shown before server echoes.
+  - Loading state: while initial resync is pending, show "Loading session…" skeleton.
+- Resync handling:
+  - `connect({ sessionId, persistentLastSeq, streamLastSeq })`. Persist anchors after every applied event:
+    - `persistentLastSeq = max(seq of last applied PersistentEvent)`.
+    - `streamLastSeq = max(seq of last applied event of any kind)`.
+  - If daemon returns `mode === "full_reload"`, drop projector state and re-render from scratch using returned events.
+  - If `mode === "persistent_fallback"`, append returned persistent events; transients before the boundary are gone (acceptable; CLI behaves the same).
+  - If `mode === "stream_resume"`, just append.
+- Markdown / formatting v1: render text as preformatted with line wrapping. Code blocks not specially handled v1; skip syntax highlighting to keep this spec focused.
+
+## Not In Scope
+
+- `cancel` (S0038).
+- `New Chat` (S0039).
+- Multi-client conflict UX beyond what daemon already broadcasts.
+- Rewind / fork / compact UI.
+- File attachments, images, audio.
+- Markdown rendering library, syntax highlighting, math, mermaid.
+- Tool result rendering specialization (e.g., diff viewer for Edit results) — generic JSON dump is fine v1.
+
+## Acceptance Criteria
+
+- Opening a session in WebUI:
+  - Renders cached events instantly when attach-cache is present.
+  - Issues a resync `connect` with persistent + stream anchors.
+  - Shows the same transcript as a parallel `scorel attach` against the same daemon (within event ordering tolerance).
+- Sending a prompt: composer clears, optimistic user turn appears, daemon echoes the persisted user message, assistant streaming text accumulates, final assistant message and any tool calls appear.
+- Reloading the WebUI tab restores the chatbox from cache, then resyncs and continues live.
+- Daemon-side persistent fallback (force by clearing daemon ring buffer) still produces a continuous transcript.
+- attach-cache size stays under ~1.5MB per session for a typical 100-turn run; quota eviction never silently drops the active session.
+- `pnpm --filter @scorel/webui typecheck && pnpm --filter @scorel/webui test` passes.
+- Repo `pnpm typecheck && pnpm test` passes.
+- Manual: real daemon + real LLM provider; send "list files in cwd" prompt that invokes a tool; verify event stream renders correctly; reload tab; transcript preserved.
+
+## Tests
+
+- Projector unit tests covering: streaming delta merge, dedup, tool call/result grouping, full_reload reset.
+- attach-cache tests for: append, truncate transients on turn_end, quota fallback ordering (transients → LRU).
+- session attach tests with a fake `DaemonClient`: mode handling for stream_resume, persistent_fallback, full_reload.
+- Component test for chatbox renderer (render fixture transcript; assert turn order and content).
+- Manual: as above.
+
+## Affected Paths
+
+- `apps/webui/lib/connection/session.ts` (new)
+- `apps/webui/lib/connection/session.test.ts` (new)
+- `apps/webui/lib/store/attach-cache.ts` (new)
+- `apps/webui/lib/store/attach-cache.test.ts` (new)
+- `apps/webui/lib/events/projector.ts` (new)
+- `apps/webui/lib/events/projector.test.ts` (new)
+- `apps/webui/lib/identity/scope-key.ts` (new — SubtleCrypto-based scope key)
+- `apps/webui/lib/identity/scope-key.test.ts` (new)
+- `apps/webui/components/chatbox/transcript.tsx` (new)
+- `apps/webui/components/chatbox/composer.tsx` (new)
+- `apps/webui/components/chatbox/turn-user.tsx` (new)
+- `apps/webui/components/chatbox/turn-assistant.tsx` (new)
+- `apps/webui/components/chatbox/turn-tool.tsx` (new)
+- `apps/webui/app/devices/[deviceId]/projects/[projectSlug]/sessions/[sessionId]/page.tsx`
+- `docs/ROADMAP.md` (M5 step entry for S0037)
+
+## Risks And Boundaries
+
+- The CLI projector logic in `apps/cli/src/index.ts` is the reference. Lift the algorithm; don't reinvent. Future spec can move it into `@scorel/client/reducer.ts`; this spec keeps it inside `apps/webui` to avoid scope creep.
+- `localStorage` write throttling: every event causes a write today. If profiling shows hot path, batch writes via `requestIdleCallback` in a follow-up.
+- Streaming text smoothness depends on event flush cadence; rely on daemon's existing transient delta cadence; do not add WebUI-side animation v1.
+- Multi-tab same-session: each tab subscribes independently; both apply the same events. Acceptable but doubles localStorage writes; document.
+- Markdown / code rendering deferred. Plain text v1 is honest; users who want pretty output add it later.
+- attach-cache scope key uses SubtleCrypto, which is async. The first event in a session waits for the key promise; cache that promise per (deviceId, projectSlug, sessionId).