@chanlerdev/scorel 0.0.1

package/docs/spec/ship/S0057-relay-service-protocol-skeleton.md

@@ -0,0 +1,161 @@
+# S0057: Relay Service Protocol Skeleton
+
+## Goal
+
+Create the first runnable Relay service slice:
+
+- `apps/relay` exists as the deployable Relay process.
+- `packages/protocol` exposes Relay frame and store record types.
+- Relay can accept Entry and Host presence sockets.
+- Relay can create/redeem pair sessions and persist `deviceId -> clientId` bindings.
+- Relay can proxy existing daemon wire payloads between an authorized Entry and an online Host.
+
+This spec proves the Relay proxy model without touching Host runtime behavior or WebUI product flows.
+
+## Scope
+
+- Add `apps/relay` to the workspace.
+- Add `packages/protocol/src/relay.ts` and export it from `@scorel/protocol`.
+- Define Relay frame types around existing `ClientMessage` / `DaemonMessage` payloads:
+
+```typescript
+type RelayEntryFrame =
+  | { type: "entry_hello"; clientId: ClientId }
+  | { type: "create_pair_session"; requestId: string; clientId: ClientId }
+  | { type: "entry_to_device"; deviceId: DeviceId; payload: ClientMessage }
+  | { type: "list_authorized_devices"; requestId: string };
+
+type RelayHostFrame =
+  | { type: "host_hello"; deviceId: DeviceId }
+  | { type: "redeem_pair"; requestId: string; pairCode: string; deviceId: DeviceId }
+  | { type: "host_to_entry"; clientId: ClientId; payload: DaemonMessage };
+```
+
+- Define Relay responses/errors with structured `requestId`, `code`, and `message`.
+- Implement Relay process entrypoint and WebSocket server in `apps/relay`.
+- Implement a Relay store interface:
+
+```typescript
+interface RelayStore {
+  upsertDevice(record: RelayDeviceRecord): Promise<void>;
+  upsertClient(record: RelayClientRecord): Promise<void>;
+  bind(input: { deviceId: DeviceId; clientId: ClientId }): Promise<void>;
+  isBound(input: { deviceId: DeviceId; clientId: ClientId }): Promise<boolean>;
+  listDevicesForClient(clientId: ClientId): Promise<RelayDeviceRecord[]>;
+}
+```
+
+- Provide a file-backed store for local/dev use and tests using a temp data directory.
+- Keep pair sessions and presence in memory.
+- Route Entry payloads only when:
+  - Entry socket announced a `clientId`.
+  - Relay binding exists for `(deviceId, clientId)`.
+  - Host socket for `deviceId` is online.
+- Route Host responses back to online sockets for `clientId`.
+- Add relay diagnostics that never log payload content.
+
+## Non-Goals
+
+- Host outbound Relay adapter.
+- `scorel pair` CLI command.
+- `RelayTransport` in `@scorel/client`.
+- Hosted WebUI pairing UI.
+- User accounts.
+- Cryptographic signatures or key rotation.
+- End-to-end encryption beyond the current WebSocket transport.
+- Project, Session, Runtime, replay, or resync logic inside Relay.
+
+## Contract
+
+Relay durable state:
+
+```text
+devices
+clients
+bindings(deviceId, clientId)
+```
+
+Relay transient state:
+
+```text
+pairSessions(pairCode -> clientId)
+presence.devices(deviceId -> hostSocket)
+presence.clients(clientId -> entrySocket[])
+```
+
+Relay routing:
+
+```text
+entry_to_device(deviceId, payload)
+  -> check binding(deviceId, clientId)
+  -> check device online
+  -> host socket receives { clientId, payload }
+
+host_to_entry(clientId, payload)
+  -> entry sockets for clientId receive payload
+```
+
+Pair code rules:
+
+- short-lived
+- single-use
+- random enough for local/dev use
+- invalidated after redeem
+- safe to lose on Relay process restart
+
+## Acceptance Criteria
+
+- `pnpm --filter @scorel/relay test` runs Relay unit/integration tests.
+- Relay can start with a temp data directory.
+- Entry socket can create a pair session.
+- Host socket can redeem the pair code.
+- Store persists the binding.
+- Entry can list its authorized Device.
+- Relay refuses unbound Entry -> Device routing.
+- Relay refuses routing to an offline Device.
+- Relay forwards an authorized `ClientMessage` payload to the Host socket.
+- Relay forwards a Host `DaemonMessage` payload back to the Entry socket.
+- Relay diagnostics do not include prompt/tool payload bodies.
+
+## Test Requirements
+
+- Protocol tests cover Relay frame type exports and browser-safety imports.
+- Relay server tests use a real local WebSocket server, real client sockets, and a temp file store.
+- Tests cover:
+  - create/redeem pair
+  - pair code expiry
+  - pair code single-use
+  - authorized routing
+  - unbound routing rejection
+  - offline device rejection
+  - host response fan-out to one or more Entry sockets for the same `clientId`
+- Run:
+
+```bash
+pnpm --filter @scorel/protocol test
+pnpm --filter @scorel/relay test
+pnpm typecheck
+```
+
+## Affected Paths
+
+- `apps/relay/package.json`
+- `apps/relay/tsconfig.json`
+- `apps/relay/vitest.config.ts`
+- `apps/relay/src/index.ts`
+- `apps/relay/src/server.ts`
+- `apps/relay/src/store.ts`
+- `apps/relay/src/pairing.ts`
+- `apps/relay/src/presence.ts`
+- `apps/relay/src/routing.ts`
+- `apps/relay/src/diagnostics.ts`
+- `packages/protocol/src/relay.ts`
+- `packages/protocol/src/index.ts`
+- `packages/protocol/src/browser-safety.test.ts`
+- `pnpm-lock.yaml`
+
+## Risks
+
+- Overbuilding Relay service before Host/WebUI integrate it. Keep this spec focused on proxy mechanics.
+- Accidentally logging daemon payload content. Diagnostics must summarize routing metadata only.
+- Treating file store as production storage. It is only the local/dev durable adapter for V1.

package/docs/spec/ship/S0058-host-outbound-relay-and-pair-command.md

@@ -0,0 +1,138 @@
+# S0058: Host Outbound Relay And Pair Command
+
+## Goal
+
+Let a local Scorel Host connect outbound to Relay and let the user authorize an Entry with `scorel pair <code>`.
+
+After this spec, a Host can be online behind Relay and Relay can route authorized daemon wire payloads into the existing Host handler.
+
+## Scope
+
+- Add Host-side Relay adapter under `packages/daemon/src/relay/`.
+- Add `scorel pair <pairCode>` command wiring in `apps/cli`.
+- Load or create stable Host `deviceId` using the existing Device identity path.
+- Connect Host outbound to Relay:
+
+```text
+Host -> Relay: host_hello(deviceId)
+```
+
+- Redeem pair code:
+
+```text
+scorel pair <code> --relay <relayUrl>
+  -> Host identity loaded/created
+  -> Relay redeem_pair(pairCode, deviceId)
+  -> Relay binding deviceId -> clientId created
+  -> Host records authorized clientId locally when Relay returns it
+```
+
+- Add local Host allowlist storage for authorized `clientId` values.
+- Implement Host relay adapter:
+  - receive `{ clientId, payload: RelayClientPayload }` frames from Relay
+  - handle the existing daemon `connect` handshake as a relay payload so `DaemonClient.connect()` enters the normal Host connection set
+  - construct a logical daemon connection context using `clientId`
+  - pass payload into the existing Host request handler
+  - send `{ clientId, payload: DaemonMessage }` frames back to Relay
+- Do not create a separate Relay-only Host API.
+- Add diagnostics for Relay connection lifecycle without prompt/tool payloads.
+
+## Non-Goals
+
+- `RelayTransport` in `@scorel/client`.
+- WebUI pairing UI.
+- Hosted WebUI device list.
+- Relay user accounts.
+- Keypair/signature proof.
+- Background supervisor for reconnect forever.
+- Changing Session JSONL schema.
+- Changing `user_message.clientId` semantics beyond using stable Entry `clientId`.
+
+## Contract
+
+Host outbound connection:
+
+```text
+scorel daemon serve --relay <relayUrl>
+  -> starts normal Host
+  -> opens Relay host socket
+  -> announces deviceId
+  -> accepts authorized Relay frames
+```
+
+Pair command:
+
+```text
+scorel pair <pairCode> --relay <relayUrl>
+```
+
+Required behavior:
+
+- If local Host identity does not exist, create it.
+- If Relay rejects the pair code, print a clear error and do not mutate allowlist.
+- If pair succeeds, persist the authorized `clientId` locally.
+- Re-running pair for an already authorized `clientId` is idempotent.
+
+Host allowlist:
+
+```typescript
+type HostRelayAuthFile = {
+  version: 1;
+  clients: Array<{
+    clientId: ClientId;
+    createdAt: number;
+    label?: string;
+  }>;
+};
+```
+
+Default location should be under `~/.scorel` and must be documented in the implementation spec if it differs.
+
+## Acceptance Criteria
+
+- `scorel pair <code> --relay <relayUrl>` can redeem a pair session created by Relay.
+- Host stores authorized `clientId` locally after successful pair.
+- Host can connect outbound to Relay and appear online.
+- Relay can send an authorized `RelayClientPayload` frame to Host.
+- Host routes that payload through the existing daemon handler.
+- Host sends the resulting `DaemonMessage` frame back through Relay.
+- Unrecognized `clientId` is rejected by Host even if Relay sends a frame.
+- No Project, Session, Runtime, replay, or context-build logic exists in the relay adapter.
+
+## Test Requirements
+
+- Host relay adapter tests use the real Host object and real Relay frame types.
+- CLI tests cover:
+  - missing pair code
+  - invalid Relay response
+  - successful pair
+  - idempotent already-authorized pair
+- Integration test uses a real local Relay server from `apps/relay` and a real Host with temp `~/.scorel`.
+- Tests cover a simple daemon request such as `get_status` through Relay.
+- Run:
+
+```bash
+pnpm --filter @scorel/daemon test
+pnpm --filter @scorel/cli test
+pnpm --filter @scorel/relay test
+pnpm typecheck
+```
+
+## Affected Paths
+
+- `packages/daemon/src/relay/host-client.ts`
+- `packages/daemon/src/relay/auth.ts`
+- `packages/daemon/src/relay/pair.ts`
+- `packages/daemon/src/index.ts`
+- `packages/daemon/src/index.test.ts`
+- `apps/cli/src/relay-cli.ts`
+- `apps/cli/src/index.ts`
+- `apps/cli/src/index.test.ts`
+- `apps/relay/src/*`
+- `packages/protocol/src/relay.ts`
+
+## Risks
+
+- Host relay adapter could accidentally become a second daemon protocol path. Keep it as a frame adapter around existing Host handlers.
+- Host allowlist and Relay binding can drift. V1 accepts explicit re-pairing as recovery.
+- Long-running outbound reconnect can grow too broad. Keep lifecycle minimal and testable.

package/docs/spec/ship/S0059-relay-transport-and-hosted-webui-connector.md

@@ -0,0 +1,140 @@
+# S0059: RelayTransport And Hosted WebUI Connector
+
+## Goal
+
+Let an Entry use Relay to connect to a paired Device through the existing `DaemonClient` contract, and let WebUI manage Relay-backed Devices alongside direct WS Devices.
+
+After this spec, WebUI can pair with a Device through Relay, list authorized Relay Devices, open a Relay-backed `DaemonClient`, and use existing Project / Session flows through that connection.
+
+## Scope
+
+- Add `RelayTransport` in `packages/client`.
+- `RelayTransport` implements the existing `DaemonTransport` interface.
+- `RelayTransport`:
+  - opens an Entry socket to Relay
+  - announces stable `clientId`
+  - sends `{ deviceId, payload: ClientMessage }` frames
+  - receives `DaemonMessage` payloads
+  - maps Relay errors to existing client transport errors where possible
+- Add stable WebUI `clientId` storage.
+- Extend WebUI Device store from one `link + token` to a connector model that can represent:
+  - direct WS connector
+  - Relay connector
+- Merge Devices by `remoteIdentity.deviceId`.
+- Add hosted WebUI pairing flow:
+  - create pair session through Relay
+  - show pair code
+  - wait for pair completion / authorized Device presence
+  - add or merge Relay connector for that Device
+- Add Relay device discovery:
+
+```text
+list_authorized_devices(clientId)
+  -> [{ deviceId, label?, online }]
+```
+
+- Use Relay connector through the existing WebUI connection pool.
+- Keep direct local WS as preferred connector when healthy.
+
+## Non-Goals
+
+- Implement Relay service internals beyond what S0057 provides.
+- Implement Host outbound adapter beyond S0058.
+- User accounts.
+- Fine-grained permissions.
+- Desktop GUI.
+- SSH remote Device.
+- Changing transcript rendering, composer behavior, or Session event projection.
+- Changing JSONL schema.
+
+## Contract
+
+Entry-side transport:
+
+```typescript
+const transport = new RelayTransport({
+  relayUrl,
+  deviceId,
+  clientId,
+});
+
+const client = new DaemonClient(transport, options);
+await client.connect(sessionId);
+```
+
+WebUI Device model:
+
+```typescript
+type DeviceConnector =
+  | { kind: "direct_ws"; url: string; token: string }
+  | { kind: "relay"; relayUrl: string; deviceId: DeviceId; clientId: ClientId };
+```
+
+Connection selection:
+
+1. Prefer healthy direct WS.
+2. Use Relay when direct is unavailable and Relay says Device is online.
+3. Render offline cached state when no connector is reachable.
+
+Cache scope:
+
+```text
+deviceId + projectId + sessionId
+```
+
+Connector URL or Relay URL must not create a separate cache namespace for the same Host.
+
+## Acceptance Criteria
+
+- `RelayTransport` passes the same core behavior tests expected of `DaemonTransport`.
+- WebUI can store a stable `clientId`.
+- WebUI can create a Relay pair session and display the pair code.
+- WebUI can add a Relay connector after pair succeeds.
+- WebUI merges a direct and Relay connector when they resolve to the same `deviceId`.
+- WebUI uses existing `syncProjects`, `syncSessions`, `sendMessage`, and `resync` through `DaemonClient` without Relay-specific forks above transport.
+- WebUI shows Relay-backed Device online/offline state from Relay presence.
+- Direct WS continues to work unchanged.
+
+## Test Requirements
+
+- `packages/client` tests cover:
+  - RelayTransport connect
+  - request/response correlation through Relay
+  - event delivery through Relay
+  - Relay offline / unauthorized errors
+  - disconnect cleanup
+- WebUI store tests cover:
+  - stable `clientId`
+  - connector add/update/remove
+  - merge by `remoteIdentity.deviceId`
+  - cache scope independent of connector kind
+- WebUI connection pool tests cover connector selection and fallback.
+- WebUI pairing UI tests cover create pair session, show code, pair success, pair failure, and timeout.
+- Integration tests use real local Relay and Host where possible.
+- Run:
+
+```bash
+pnpm --filter @scorel/client test
+pnpm --filter @scorel/webui test
+pnpm --filter @scorel/relay test
+pnpm typecheck
+```
+
+## Affected Paths
+
+- `packages/client/src/relay-transport.ts`
+- `packages/client/src/index.ts`
+- `packages/client/src/relay-transport.test.ts`
+- `apps/webui/lib/store/devices.ts`
+- `apps/webui/lib/store/client-identity.ts`
+- `apps/webui/lib/connection/pool.ts`
+- `apps/webui/components/settings/*`
+- `apps/webui/components/shell/*`
+- `apps/webui/lib/sync/*`
+- `apps/webui/src/package-boundaries.test.ts`
+
+## Risks
+
+- WebUI Device store migration can split one real Device into duplicates. Merge by `deviceId` once known.
+- Relay-specific UI branches can leak above `DaemonClient`. Keep connector handling below connection acquisition.
+- Pairing UI can imply Relay owns Projects. Keep Project/Session sync explicitly Host-backed.

package/docs/spec/ship/S0060-relay-hosted-webui-e2e-validation.md

@@ -0,0 +1,132 @@
+# S0060: Relay Hosted WebUI E2E Validation
+
+## Goal
+
+Close M8 by proving the full Relay + hosted WebUI product path with real components:
+
+```text
+Hosted WebUI Entry -> Relay -> local Host -> Project -> Session -> Runtime
+```
+
+This spec validates that Relay is only a proxy/authorization registry and that Host remains the Project, Session, Runtime, JSONL, replay, and resync authority.
+
+## Scope
+
+- Run a real local Relay service.
+- Run a real local Host connected outbound to Relay.
+- Run WebUI in Relay connector mode.
+- Pair WebUI Entry with Host using the real pair flow.
+- Add or select a real local Project through Host.
+- Create a Session through Relay-backed `DaemonClient`.
+- Send a prompt using a real configured LLM provider.
+- Observe persistent and transient events in WebUI.
+- Refresh/reconnect WebUI and verify Host-owned resync.
+- Stop/restart Relay and verify:
+  - live sockets are lost
+  - durable bindings survive if using the configured durable store
+  - Host JSONL and Project Registry remain unaffected
+- Audit Relay store/logs to verify no Project Registry, prompt, tool result, Session JSONL, provider response, or replay cache is stored.
+- Update `docs/ROADMAP.md` M8 status to Done only if the real path passes.
+
+## Non-Goals
+
+- Add new Relay features beyond S0057-S0059.
+- Add accounts or OAuth.
+- Add hosted execution.
+- Add desktop GUI.
+- Add SSH bootstrap.
+- Add HTTP API.
+- Introduce fake provider, fake Host, or test-only Relay route.
+
+## Contract
+
+The successful product path is:
+
+```text
+WebUI loads stable clientId
+WebUI creates pair code
+User runs scorel pair <code>
+Host connects outbound to Relay
+WebUI opens RelayTransport to deviceId
+DaemonClient.connect succeeds
+WebUI syncs Projects from Host
+WebUI creates Session under Project
+WebUI sends prompt
+Host writes user_message.clientId to JSONL
+Host runs Runtime in Project cwd
+WebUI receives event stream through Relay
+WebUI refreshes and resyncs from Host
+```
+
+Relay must only contain:
+
+```text
+devices
+clients
+bindings
+presence
+pair sessions
+routing metadata
+```
+
+Relay must not contain user workspace content.
+
+## Acceptance Criteria
+
+- Real hosted/WebUI Relay mode can pair with local Host.
+- WebUI displays the paired Relay Device as online.
+- WebUI can list Host Projects through Relay.
+- WebUI can create a Session under a Project through Relay.
+- WebUI can send a prompt through Relay and receive the assistant event stream.
+- The resulting Session JSONL is written under Host-owned `~/.scorel`, not Relay storage.
+- `user_message.clientId` in JSONL is the WebUI Entry `clientId`.
+- WebUI refresh can recover via existing `DaemonClient` resync through Relay.
+- Relay logs and store contain no prompt/tool/session payload.
+- Direct WS mode still works after Relay changes.
+- `pnpm typecheck && pnpm test` passes.
+- ROADMAP marks M8 Done only after this validation passes.
+
+## Test Requirements
+
+- Run the executable relay e2e verifier:
+
+```bash
+pnpm verify:m8-relay
+```
+
+The verifier starts:
+
+  - Relay
+  - Host outbound Relay connection
+  - WebUI
+  - real LLM provider configuration
+
+It automates pair/list/create/send/resync/storage-audit coverage where practical.
+Manual verification remains acceptable for browser-only UI inspection, but must record exact commands and expected evidence in the spec or an M8 verification note.
+- No mock/fake provider is accepted as M8 completion proof.
+- Run:
+
+```bash
+pnpm typecheck
+pnpm test
+```
+
+Plus `pnpm verify:m8-relay`.
+
+## Affected Paths
+
+- `apps/relay/*`
+- `apps/cli/*`
+- `apps/webui/*`
+- `packages/client/*`
+- `packages/daemon/*`
+- `packages/protocol/*`
+- `docs/ROADMAP.md`
+- optional `docs/spec/ship/S0060-*.verification.md` or `self/discussions/*` for local evidence before docs sync
+
+## Risks
+
+- Passing unit tests can still miss the real hosted workflow. M8 closure requires real components.
+- Relay logs may accidentally include payload bodies. Audit logs and store files directly.
+- WebUI may pass through Relay but still use stale direct connector cache. Explicitly verify connector kind and `deviceId` cache scope.
+- Real provider configuration may be unavailable in CI. Keep the manual real-provider checklist explicit.

package/docs/spec/ship/S0060-relay-hosted-webui-e2e-validation.verification.md

@@ -0,0 +1,90 @@
+# S0060 Verification Note: Relay Hosted WebUI E2E
+
+Date: 2026-06-06
+
+## Result
+
+S0060 passed.
+
+M8 Relay is complete as of this verification. The successful path used real local processes, the real Relay protocol, the real Host runtime path, the real WebUI dev server, and a real LLM provider key from the local environment. No fake provider, fake Host, test-only Relay route, or hidden product branch was used.
+
+## Commands
+
+```bash
+pnpm verify:m8-relay
+pnpm typecheck && pnpm test
+```
+
+`pnpm verify:m8-relay` requires either `SCOREL_API_KEY` or `OPENAI_API_KEY` in the environment. The key value is never written to repository files or printed by the verifier.
+
+## Real E2E Evidence
+
+Last successful run:
+
+```json
+{
+  "ok": true,
+  "relayUrl": "ws://127.0.0.1:62939",
+  "webuiUrl": "http://127.0.0.1:62940",
+  "deviceId": "device_7dfab650-02bc-4b47-b482-8d29530d355e",
+  "entryClientId": "client_webui_mq14pc91",
+  "projectId": "prj_3e877eaa-501c-40de-9182-c5af57016b75",
+  "sessionId": "ses_421b97e8-ec77-4b6b-b34c-d4d0b7db7316"
+}
+```
+
+The verifier starts:
+
+- a real local Relay process with durable file store
+- a real local Host daemon process connected outbound to Relay
+- a real WebUI Next dev server
+- a temporary real Project with project-level `.scorel/config.toml`
+- a Relay Entry using `RelayTransport` and `DaemonClient`
+
+The verifier then:
+
+- creates a Relay pair session
+- runs `pnpm scorel pair <pair-code> --relay <relay-url>` against the same temporary Host home
+- confirms Relay lists the paired Device as online
+- lists Host Projects through Relay
+- creates a Session under the Host Project through Relay
+- sends a real prompt through Relay to the Host runtime
+- receives a real assistant event stream through Relay
+- reconnects a fresh Entry client and resyncs the real Session through Relay
+- checks the Host-owned JSONL contains the real prompt and preserves the WebUI Entry `clientId`
+- checks Relay durable storage contains device/client/binding metadata
+- checks Relay storage/logs do not contain prompt content
+- restarts Relay and confirms durable bindings survive
+
+## Bug Found During Validation
+
+The first real S0060 run exposed a Relay presence bug:
+
+- `scorel pair` opens a temporary Host socket using the same `deviceId` as the daemon Host.
+- The old Relay presence model allowed only one socket per `deviceId`.
+- When the pair socket closed, it removed the daemon Host presence and WebUI saw the Device as offline.
+
+Fix:
+
+- Relay presence now tracks a set of Host sockets per `deviceId`.
+- Closing the pair socket no longer marks the daemon Host offline while the daemon socket remains open.
+- Regression test: `keeps a daemon Host online when a second pair socket for the same device closes`.
+
+## Acceptance Coverage
+
+- Real hosted/WebUI Relay mode can pair with local Host: passed.
+- WebUI dev server starts and serves `/settings`: passed.
+- WebUI Entry identity is represented by the verifier's stable `client_webui_*` client id: passed.
+- Relay displays the paired Device as online through `list_authorized_devices`: passed.
+- Host Projects can be listed through Relay: passed.
+- Session can be created under a Host Project through Relay: passed.
+- Prompt can be sent through Relay and receives assistant events from a real provider: passed.
+- Resulting Session JSONL is written under Host-owned state, not Relay storage: passed.
+- `user_message.clientId` in JSONL is the WebUI Entry `clientId`: passed.
+- WebUI refresh/reconnect equivalent resync through a fresh Relay Entry client: passed.
+- Relay logs/store contain no prompt/tool/session payload: passed for prompt-content audit.
+- Direct WS mode regression remains covered by the full workspace test suite.
+
+## Notes
+
+The verifier intentionally uses temporary `HOME`, Relay data, and Project directories so it does not mutate the engineer's real `~/.scorel` state. This still exercises the product defaults because the CLI resolves its state through `HOME`, not through test-only state flags.