@chanlerdev/scorel 0.0.1

package/docs/spec/ship/S0025-remote-attach-session-event-view.md

@@ -0,0 +1,57 @@
+# S0025: Remote Attach Session Event View
+
+## Goal
+
+Fix `scorel attach` so every attached terminal behaves as a consistent session event view.
+
+User messages, final assistant messages, tool results, and recoverable events must be visible to all attached clients. A reconnect must recover missed persistent session state from the daemon instead of relying only on live transient deltas.
+
+## Scope
+
+- Render `user_message` events in attached terminals so all clients see the same submitted prompts.
+- Render missed persistent `assistant_message` and `tool_result` events returned by `load_session` / `resync_events`.
+- Keep live `text_delta` rendering for in-flight assistant output.
+- Avoid duplicating final assistant text when a client already rendered its live deltas.
+- Add terminal line boundary handling so passive clients do not leave the next user input prompt on the same line as assistant output.
+- Make explicit `create_session` idempotent enough for concurrent attach clients racing to create the same session id.
+- Keep local socket attach and remote WebSocket attach on the same CLI code path.
+- Validate with real daemon/client processes and the real provider path.
+
+## Not In Scope
+
+- Byte-for-byte replay of transient text deltas that were emitted before a client connected.
+- Automatic network reconnect loop after a socket closes.
+- Full TUI/editor prompt management.
+- Per-client scrollback preferences.
+- Cancel/interrupt propagation.
+
+## Acceptance Criteria
+
+- Two remote `scorel attach` clients connected to one session both display a submitted `user_message`.
+- A client that reconnects after a turn completes can display missed persistent assistant output from JSONL-backed daemon state.
+- A client that reconnects while a turn is still running recovers persisted events already committed and continues to receive future live events.
+- Two clients attaching to the same missing session at the same time do not leave either client stuck waiting for `create_session`.
+- Passive terminal output has clean line boundaries between session events and user input.
+- `pnpm check` passes.
+
+## Tests
+
+- Add focused CLI tests for persistent event rendering and terminal boundaries.
+- Run `pnpm --filter @scorel/app-cli test`.
+- Run `pnpm check`.
+- Run manual real-process validation with one `scorel-daemon serve` process and two `scorel attach --remote` clients sharing one session.
+
+## Affected Paths
+
+- `apps/cli/src/index.ts`
+- `apps/cli/src/index.test.ts`
+- `packages/daemon/src/index.ts`
+- `packages/daemon/src/embedded/embedded.test.ts`
+- `docs/ROADMAP.md`
+- `self/discussions/2026-05-29-m4-remote-control-planning.md`
+
+## Risks And Boundaries
+
+- The reliable recovery source is persistent session JSONL. Transient events remain best-effort live UI events.
+- The CLI must not add a hidden test-only mode, fake transport, or fake protocol branch.
+- Rendering should be idempotent by event id so reconnect/resync does not duplicate already displayed persistent messages.

package/docs/spec/ship/S0026-attach-project-cache-and-dual-seq-reconnect.md

@@ -0,0 +1,87 @@
+# S0026: Attach Project Cache And Dual-Seq Reconnect
+
+## Goal
+
+Fix attach recovery so local and remote project sessions can resume from a client-owned persistent cache, while reconnect semantics remain aligned with daemon authority.
+
+This spec closes the gap left by S0024/S0025: reconnect must distinguish between durable client state and previously seen stream state, support project-scoped session storage for both local and remote projects, and continue live streaming after persistent fallback.
+
+## Scope
+
+- Introduce a project-scoped session storage model for attach-visible session persistence instead of treating all sessions as flat global files.
+- Define local and remote project identity at the same abstraction level:
+  - local projects under a local scope
+  - remote projects under a remote device scope
+- Remote attach cache identity is `deviceId + projectSlug + sessionId`. The connection URL is a transport endpoint and may be used only as a fallback before daemon identity is known.
+- Daemon connection metadata must expose a stable `deviceId`, optional user-facing `deviceDisplayName`, and a stable `projectSlug` for the served project.
+- Store client-visible persistent session backlog under the project scope so attach can render local persistent history before daemon reconciliation.
+- Store in-progress assistant transient text under the same project scope when the client has durable stream anchors, so a process restart can display the already-seen prefix before asking daemon to continue from `streamLastSeq`.
+- Define dual reconnect anchors:
+  - `persistentLastSeq`: highest seq guaranteed by locally persisted persistent events
+  - `streamLastSeq`: highest seq the client has actually observed in the event stream
+- Upgrade reconnect/resync contract so daemon can distinguish:
+  - stream resume from buffer
+  - persistent-only fallback
+  - full reload
+- Define persistent fallback semantics precisely:
+  - daemon only replays missing persistent events
+  - client immediately returns to live subscription after fallback completes
+  - lost transient continuity before the fallback boundary is treated as unrecoverable, not silently reconstructed
+- Define the cutover boundary between fallback replay and subsequent live stream so fallback does not skip live events produced during recovery.
+- Define cache mismatch behavior for stdout-only clients that cannot visually roll back pre-rendered history.
+- Keep local attach and remote attach on the same product path and cache model.
+- Update spec/docs language so `lastSeq` is no longer treated as a single sufficient reconnect anchor once client-owned cache exists.
+
+## Not In Scope
+
+- Full byte-for-byte reconstruction of transient events after client process restart.
+- Full TUI scrollback manager or editor-like terminal persistence.
+- Automatic daemon crash recovery beyond current daemon-owned session persistence.
+- Relay/tunnel/public remote service features.
+- Background reconnect daemon running outside the CLI attach process.
+
+## Acceptance Criteria
+
+- A local attach client and a remote attach client both map their session persistence through a project-scoped directory instead of a flat global session file assumption.
+- Remote project sessions are separated from local project sessions by `deviceId + projectSlug` scope and do not collide with same-path local workspaces.
+- If the same remote daemon project is reached through a different URL, attach can still reuse cache when daemon reports the same `deviceId + projectSlug`.
+- `deviceDisplayName` is metadata for user-facing labels only; it must not replace stable `deviceId` in cache identity.
+- Reconnect protocol explicitly carries both `persistentLastSeq` and `streamLastSeq`.
+- If daemon buffer covers `streamLastSeq`, reconnect resumes the stream from `streamLastSeq + 1`.
+- If daemon buffer does not cover `streamLastSeq` but client has persistent cache, daemon falls back to replaying only missing persistent events after `persistentLastSeq`, then the connection continues receiving future live transient and persistent events.
+- Client can tell whether reconnect result was `stream_resume`, `persistent_fallback`, or `full_reload`; the mode is not inferred implicitly.
+- Daemon proves buffer coverage by checking that the buffered stream continuously covers `streamLastSeq + 1`; having any later buffered event is not enough.
+- In `persistent_fallback`, `throughSeq` is the highest replayed persistent seq, not blindly the daemon current seq. Future live events with higher seq remain deliverable after the replay response.
+- CLI attach pre-renders only cache entries whose project/session metadata match the requested attach target; if daemon reconciliation reports `full_reload`, stale printed cache is separated from authoritative replay instead of being silently treated as current history.
+- Cold-start attach does not claim stream resume from a transient seq unless the client has durable transient anchors for that stream. Without such anchors, it uses the persistent anchor and accepts fallback semantics.
+- Resynced transient events returned in `resync_events.events` are delivered to subscribers/renderers, not only folded into internal client state.
+- CLI attach reads input into a queue and serializes sends, so lines typed or pasted while a turn is running are queued instead of being hidden behind the pending `sendMessage` await.
+- `pnpm typecheck && pnpm test` passes.
+- Manual validation covers one real remote daemon and one local attach client reconnecting through the new semantics.
+
+## Tests
+
+- Add focused protocol/client/CLI tests for dual-seq reconnect semantics.
+- Add tests for project-scope session directory resolution for local and remote projects.
+- Add tests proving persistent fallback returns to live event streaming instead of leaving the client in replay-only mode.
+- Add tests for buffer gap detection, fallback `throughSeq` cutover, same `sessionId` under different project scopes, and duplicate-free CLI rendering from cache + daemon replay.
+- Run `pnpm typecheck && pnpm test`.
+- Run one manual real-process validation with real provider path, real temporary workspace, real JSONL session, and remote reconnect.
+
+## Affected Paths
+
+- `docs/spec/client.md`
+- `docs/spec/daemon.md`
+- `docs/spec/session.md`
+- `docs/architecture.md`
+- `docs/ROADMAP.md`
+- `docs/spec/ship/S0026-attach-project-cache-and-dual-seq-reconnect.md`
+- `self/discussions/2026-05-29-attach-project-cache-dual-seq.md`
+
+## Risks And Boundaries
+
+- Project key design must stay readable without using fragile reversible path encoding as the source of truth; metadata must preserve the real locator.
+- `deviceId` is sufficient as a remote namespace only if project metadata also stores the original remote workspace locator.
+- Dual-seq reconnect adds protocol complexity; daemon and client must share one exact recovery-state model to avoid hidden divergence.
+- Persistent cache is a client-side acceleration and recovery aid, not a replacement for daemon session authority.
+- Terminal stdout cannot retract stale cache output. CLI must prefer conservative rendering and explicit recovery markers over optimistic UI tricks that only work in GUI clients.

package/docs/spec/ship/S0027-session-diagnostics-log.md

@@ -0,0 +1,77 @@
+# S0027: Session Diagnostics Log
+
+## Goal
+
+Add a per-session diagnostics log so provider, runtime, daemon, and reconnect failures are visible without overloading session JSONL or attach cache.
+
+Session JSONL remains the replayable product record. Attach cache remains a client-side terminal recovery aid. Diagnostics logs are daemon-owned debugging evidence stored beside the daemon session file.
+
+## Scope
+
+- Store a diagnostics log beside each daemon-owned session JSONL file:
+  - session: `<sessionsDir>/<sessionId>.jsonl`
+  - diagnostics log: `<sessionsDir>/<sessionId>.log`
+- Use append-only plain text `.log` lines, one log entry per line.
+- Keep lines human-readable and grep-friendly, with stable key/value fields where useful.
+- Record enough detail to debug failed real-provider turns:
+  - session create/load
+  - client connect/disconnect identity
+  - `send_message` start/end
+  - runtime turn start/end
+  - provider-visible assistant result summary
+  - runtime/provider errors with message and short stack
+  - resync mode and anchor values
+- Keep logs on the machine that owns the daemon session:
+  - embedded/local daemon logs live beside local session JSONL
+  - remote daemon logs live beside remote session JSONL
+  - local attach cache does not store daemon diagnostics
+- Add a minimal CLI read path for local files, enough to inspect the current machine's session diagnostics.
+
+## Not In Scope
+
+- Log levels, log rotation, retention policy, compression, or upload.
+- GUI log viewer.
+- Remote log retrieval over the daemon protocol.
+- Logging full prompt text, full tool results, full provider payloads, or secrets.
+- Changing the session JSONL event schema.
+- Making attach cache authoritative or diagnostic.
+
+## Acceptance Criteria
+
+- Creating or loading a session can create/use `<sessionsDir>/<sessionId>.log` beside `<sessionId>.jsonl`.
+- `send_message` writes start and finish log lines including `sessionId`, `clientId`, and resulting event ids.
+- Runtime/provider errors write a line containing the error message and a short stack excerpt.
+- Assistant result log lines include `stopReason`, text block count, tool call count, and usage when present.
+- `resync_events` writes a line with recovery mode, `persistentLastSeq`, `streamLastSeq`, `throughSeq`, and returned event count.
+- Connect/disconnect logs include client id, daemon `deviceId`, optional display name, and project slug when available.
+- Logs do not include bearer tokens or API keys.
+- `scorel logs --session <id>` can print the local `<sessionId>.log`; `--tail <n>` limits output to the last `n` lines.
+- `pnpm typecheck && pnpm test` passes.
+
+## Tests
+
+- Add core session tests for log file path derivation beside session JSONL.
+- Add daemon tests proving `send_message`, runtime error, and resync write diagnostics lines.
+- Add CLI tests for `scorel logs --session <id>` and `--tail <n>`.
+- Run targeted package tests.
+- Run `pnpm typecheck && pnpm test`.
+
+## Affected Paths
+
+- `docs/ROADMAP.md`
+- `docs/spec/session.md`
+- `docs/spec/daemon.md`
+- `docs/spec/ship/S0027-session-diagnostics-log.md`
+- `packages/core/src/session/index.ts`
+- `packages/core/src/session/session.test.ts`
+- `packages/daemon/src/index.ts`
+- `packages/daemon/src/protocol.test.ts`
+- `apps/cli/src/index.ts`
+- `apps/cli/src/index.test.ts`
+
+## Risks And Boundaries
+
+- Logs can leak sensitive data if they capture raw prompts, tool results, provider payloads, tokens, or API keys. S0027 must prefer summaries and explicit error messages over raw payload dumps.
+- Plain `.log` is intentionally less structured than session JSONL. Keep key names stable enough for grep, but do not turn this into a second event protocol.
+- Remote diagnostics remain on the remote daemon host until a future spec adds remote log retrieval. S0027 should not silently copy remote logs into local attach cache.
+- Rich logging can become noisy. Keep the first version focused on lifecycle, recovery, result summaries, and errors.

package/docs/spec/ship/S0028-client-attach-diagnostics-log.md

@@ -0,0 +1,70 @@
+# S0028: Client Attach Diagnostics Log
+
+## Goal
+
+Add a client-side attach diagnostics log so local clients can debug remote attach, reconnect, cache, and rendering behavior without SSH access to the remote daemon host.
+
+S0027 added daemon-owned session diagnostics beside daemon session JSONL. S0028 adds the complementary client-owned attach diagnostics beside the local attach cache.
+
+## Scope
+
+- Store attach diagnostics beside the local attach cache file:
+  - cache: `<stateDir>/attach-cache/<scopeKey>/<sessionId>.json`
+  - attach diagnostics: `<stateDir>/attach-cache/<scopeKey>/<sessionId>.log`
+- Use append-only plain text `.log` lines, one log entry per line.
+- Keep remote and local attach on the same logging path.
+- Record client-side attach lifecycle and transport-visible behavior:
+  - cache scope resolution
+  - cache read/write summaries
+  - connect start/success/failure, with token redacted
+  - daemon connection identity (`deviceId`, `deviceDisplayName`, `projectSlug`)
+  - load/create session result
+  - resync anchors and resync mode
+  - inbound events rendered by attach, including event type and seq
+  - outbound user input send start/finish/error
+  - disconnect/exit
+- Permit richer payload logging than S0027 because session JSONL already stores product data, but never log bearer tokens, API keys, or local secret tokens.
+- Add a CLI read path for attach logs.
+
+## Not In Scope
+
+- Remote retrieval of daemon-side `<sessionId>.log`.
+- Log rotation, retention, compression, upload, or GUI.
+- Making attach logs authoritative replay state.
+- Changing attach cache JSON shape beyond metadata needed to find the sibling log.
+- Recording raw secrets.
+
+## Acceptance Criteria
+
+- Running `scorel attach --remote ...` writes `<stateDir>/attach-cache/<scopeKey>/<sessionId>.log` next to the attach cache JSON.
+- The attach log includes cache scope identity, connect success, daemon identity, resync mode, rendered inbound events, send start/finish, and disconnect.
+- Token values are not present in attach diagnostics.
+- Local attach also writes a sibling attach diagnostics log under its local scope.
+- `scorel logs --attach --session <id> --remote <url>` can print the local attach diagnostics log for the matching remote `deviceId + projectSlug` scope after at least one connect has resolved that identity.
+- `scorel logs --attach --session <id> --tail <n>` can print local attach diagnostics for local attach scope.
+- Existing `scorel logs --session <id>` keeps reading daemon-side session diagnostics.
+- `pnpm typecheck && pnpm test` passes.
+
+## Tests
+
+- Add CLI tests that run remote attach twice through different endpoints with the same daemon identity and verify the attach log is reused beside the cache.
+- Add CLI tests that assert attach logs contain lifecycle entries and do not contain the token.
+- Add CLI tests for `scorel logs --attach --session <id> --remote <url> --tail <n>`.
+- Run targeted CLI tests.
+- Run `pnpm typecheck && pnpm test`.
+
+## Affected Paths
+
+- `docs/ROADMAP.md`
+- `docs/spec/client.md`
+- `docs/spec/session.md`
+- `docs/spec/ship/S0028-client-attach-diagnostics-log.md`
+- `apps/cli/src/index.ts`
+- `apps/cli/src/index.test.ts`
+
+## Risks And Boundaries
+
+- Attach logs can grow quickly if every event is logged in full. S0028 should log enough payload context to debug, but keep one-line entries grep-friendly.
+- Attach logs are local client evidence. They can prove what the client saw and rendered, but not provider/runtime internals on the remote daemon host.
+- Remote URL alone is not stable identity. When daemon identity is known, attach diagnostics must use the same `deviceId + projectSlug` scope as attach cache.
+- Secret redaction must be explicit and tested.

package/docs/spec/ship/S0029-project-index-for-session-lookup.md

@@ -0,0 +1,119 @@
+# S0029: Project Index For Session Lookup
+
+## Goal
+
+Add a lightweight project index so CLI and future GUI surfaces can organize local and remote sessions by project instead of by storage path shape.
+
+Session JSONL, daemon diagnostics, attach cache, and attach diagnostics already live in different physical locations. S0029 adds one lookup file that maps project identity to those existing session assets without migrating or duplicating them.
+
+## Scope
+
+- Add one index file:
+  - `<stateDir>/project-index.json`
+- Do not add a `projects/` directory.
+- Do not move existing files:
+  - `<stateDir>/sessions/<sessionId>.jsonl`
+  - `<stateDir>/sessions/<sessionId>.log`
+  - `<stateDir>/attach-cache/<scopeKey>/<sessionId>.json`
+  - `<stateDir>/attach-cache/<scopeKey>/<sessionId>.log`
+- Treat project as the user-facing organization unit:
+  - local project identity is the canonical CLI `workDir`
+  - remote project identity is the remote daemon `projectSlug`
+  - `deviceId` is a namespace/disambiguator for remote devices with the same `projectSlug`
+  - `deviceDisplayName` and project display names are UI metadata, not identity
+  - remote URL is only the latest connection endpoint, not identity
+- Update the project index from:
+  - `scorel chat` for local sessions
+  - local `scorel attach` for local attach cache/logs
+  - remote `scorel attach` for remote attach cache/logs
+- Use the project index for attach log lookup before falling back to legacy attach-cache scanning.
+
+## Not In Scope
+
+- GUI project browser.
+- Moving session/cache/log files into project directories.
+- Remote retrieval of daemon-owned session JSONL or daemon diagnostics.
+- Global search, retention, rotation, or compaction of index data.
+- Making the index authoritative session state.
+
+## Index Shape
+
+```json
+{
+  "version": 1,
+  "projects": [
+    {
+      "projectKey": "local:/Users/chanler/Scorel",
+      "kind": "local",
+      "workDir": "/Users/chanler/Scorel",
+      "displayName": "Scorel",
+      "lastSeenAt": 1716000000000,
+      "sessions": {
+        "ses_local": {
+          "sessionId": "ses_local",
+          "source": "local-session",
+          "sessionPath": "sessions/ses_local.jsonl",
+          "logPath": "sessions/ses_local.log",
+          "lastSeenAt": 1716000000000
+        }
+      }
+    },
+    {
+      "projectKey": "remote:device_vps:scorel",
+      "kind": "remote",
+      "deviceId": "device_vps",
+      "deviceDisplayName": "Tokyo VPS",
+      "projectSlug": "scorel",
+      "displayName": "scorel",
+      "lastRemoteUrl": "wss://example.invalid",
+      "lastSeenAt": 1716000000000,
+      "sessions": {
+        "ses_remote": {
+          "sessionId": "ses_remote",
+          "source": "attach-cache",
+          "cachePath": "attach-cache/abc123/ses_remote.json",
+          "logPath": "attach-cache/abc123/ses_remote.log",
+          "lastSeenAt": 1716000000000
+        }
+      }
+    }
+  ]
+}
+```
+
+The index stores relative paths from `<stateDir>` so it remains portable across test temp dirs and product roots.
+
+## Acceptance Criteria
+
+- `scorel chat --cwd <dir> --session <id>` records a local project entry keyed by the canonical `workDir`.
+- local `scorel attach --session <id>` records a local project/session entry with attach cache and attach log paths.
+- remote `scorel attach --remote <url> --session <id>` records a remote project entry keyed by `remote:<deviceId>:<projectSlug>`.
+- Remote project display/organization uses `projectSlug`; `deviceId` only disambiguates devices.
+- `lastRemoteUrl` is recorded but does not participate in identity.
+- `scorel logs --attach --session <id> --remote <url>` can resolve the attach diagnostics log through `project-index.json`.
+- If index lookup is unavailable, legacy attach-cache scanning remains as a compatibility fallback.
+- Existing session and attach cache/log paths remain unchanged.
+- `pnpm typecheck && pnpm test` passes.
+
+## Tests
+
+- Add CLI tests for local chat writing `project-index.json` with canonical workDir and session log path.
+- Add CLI tests for remote attach writing remote project index entries with `projectSlug`, `deviceId`, `lastRemoteUrl`, cache path, and log path.
+- Add CLI tests for `scorel logs --attach` reading via project index.
+- Run targeted CLI tests.
+- Run `pnpm typecheck && pnpm test`.
+
+## Affected Paths
+
+- `docs/ROADMAP.md`
+- `docs/spec/client.md`
+- `docs/spec/session.md`
+- `docs/spec/ship/S0029-project-index-for-session-lookup.md`
+- `apps/cli/src/index.ts`
+- `apps/cli/src/index.test.ts`
+
+## Risks And Boundaries
+
+- Index writes must not make session/cache writes authoritative or fragile. If the index is missing or corrupt, commands should keep working where possible.
+- Multiple projects may contain the same random `sessionId`. Lookup must prefer matching remote URL/project metadata where available and avoid silently selecting the wrong project when ambiguity is detectable.
+- The index can be rebuilt later from existing files and metadata; S0029 only creates and updates it opportunistically on product paths.

package/docs/spec/ship/S0030-webui-product-intent.md

@@ -0,0 +1,73 @@
+# WebUI Product Intent
+
+This note captures the intended WebUI product shape after rolling back the first M5 implementation attempts. It is not an implementation spec.
+
+## Core Idea
+
+WebUI is a remote-only chatbox client. It should feel like Codex App / Alma, not like a dashboard, diagnostics page, or connection form.
+
+The product hierarchy is:
+
+```text
+Device -> Project -> Session -> Chatbox
+```
+
+## Device
+
+A remote endpoint is user-facing as a Device.
+
+A Device has:
+
+- `Name`: user-visible device name.
+- `Link`: remote daemon WebSocket endpoint.
+- `Token`: remote daemon auth token.
+
+Devices are managed in a dedicated Settings page. The primary chat sidebar should not contain endpoint/token fields.
+
+## Sidebar
+
+The main sidebar should follow the Codex App / Alma interaction pattern:
+
+- top-level actions such as New Chat, Search, Skills, Plugins, Automations
+- a Projects section
+- within Projects, show Device roots
+- under each Device, show Projects
+- under each Project, show Sessions
+- a bottom Settings entry
+
+The sidebar must not show fake projects or fake sessions.
+
+## Sync Model
+
+WebUI cannot embed or manage a local daemon. It only connects to remote daemons.
+
+After a Device connects:
+
+1. read remote identity from daemon handshake
+2. sync the Project index
+3. sync Session lists under each Project
+4. lazy-load Session content when the user clicks a Session
+
+Session content should not be eagerly loaded for every session.
+
+Browser-side storage should use `localStorage` only. WebUI must not write JSONL files or daemon attach caches.
+
+## Chatbox
+
+Opening a Session should show a normal chatbox:
+
+- transcript/event stream in the main area
+- user/assistant/tool/status events in chronological order
+- bottom composer
+- send/cancel controls
+- shared remote daemon session state with other clients
+
+Settings and connection management are not the main chat surface.
+
+## Out Of Scope For M5
+
+- GUI / Tauri / Electron
+- local daemon process manager
+- account auth / OAuth / relay / NAT traversal
+- IDE-style file explorer or monitoring dashboard
+- full rewind/fork/compact UI

package/docs/spec/ship/S0031-daemon-projectslug-rule.md

@@ -0,0 +1,72 @@
+# S0031: Daemon ProjectSlug Generation Rule
+
+## Goal
+
+Lock how `EmbeddedDaemon` generates the `projectSlug` it exposes to clients, so daemon-side identity becomes self-determined instead of opaque options pass-through.
+
+S0026 / S0029 already require `projectSlug` to be a stable, daemon-owned identifier. Neither spec defines the string-construction rule. Today `EmbeddedDaemon` accepts `projectSlug?` as a constructor option and forwards it verbatim through handshake / event metadata / diagnostics; whatever the embed host hands in becomes the slug. That is fragile and forces every entry point (CLI / future remote daemon CLI / future GUI host) to invent the same rule independently.
+
+This spec adopts the codebuddy-style rule (`/Users/chanler/personal/Scorel` → `Users-chanler-personal-Scorel`) inside `@scorel/daemon`, removes slug construction from embed hosts, and makes the slug deterministic from the daemon working directory.
+
+## Scope
+
+- Add `packages/daemon/src/projects/slug.ts` exporting:
+  - `toProjectSlug(absolutePath: string): string`
+  - `fromProjectSlug(slug: string): string | null` (best-effort `-` → `/` reverse with leading `/`; returns null if obviously invalid)
+- Replace `EmbeddedDaemon` constructor option `projectSlug?: string` with `workDir: string`. The daemon computes `projectSlug = toProjectSlug(workDir)` internally.
+- Keep `deviceId` / `deviceDisplayName?` constructor options unchanged.
+- Update `apps/cli/src/index.ts` (every `EmbeddedDaemon` instantiation) to pass `workDir` instead of `projectSlug`.
+- Keep handshake / event metadata / diagnostics shapes unchanged: they continue to carry `projectSlug` over the wire.
+- Slug rule:
+  1. Resolve input to absolute path. POSIX paths only on day one (Windows pass-through ok, but documented as best-effort: drive letter `:` removed, `\` and `/` both treated as separator).
+  2. Strip leading `/`.
+  3. Replace every remaining `/` with `-`.
+  4. Empty input → throw; `/` (root) → `root` (single segment fallback).
+  5. No hashing, no URL-encoding, no truncation.
+
+## Not In Scope
+
+- Changing `~/.scorel/sessions/` directory layout. Sessions remain flat; per-S0029 "do not move existing files".
+- Daemon-side `list_projects` / `list_sessions` protocol (lives in S0032).
+- Reverse-lookup correctness when `-` appears inside a path segment. Daemon must persist `workDirHint` separately if it ever needs accurate reverse mapping (out of S0031 scope; covered by future spec when `list_projects` is added).
+- WebUI / CLI client-side slug computation. Clients consume slugs from daemon, never compute them.
+- TLS / auth / session creation behavior.
+
+## Acceptance Criteria
+
+- `packages/daemon/src/projects/slug.ts` exposes `toProjectSlug` with the rule above; unit tests cover:
+  - `/Users/chanler/personal/Scorel` → `Users-chanler-personal-Scorel`
+  - `/home/alice/repo` → `home-alice-repo`
+  - `/` → `root`
+  - empty / non-string → throws
+  - relative paths get resolved to absolute through `path.resolve`; tests pin behavior with a `cwd` fixture
+- `EmbeddedDaemonOptions.projectSlug` removed; `workDir: string` added and required.
+- All `EmbeddedDaemon` constructions in `apps/cli/src/index.ts` and tests pass `workDir`. No CLI-side slug construction remains.
+- `connect` result, `connected` daemon message, `client_connected` diagnostics all carry the daemon-computed `projectSlug`.
+- `pnpm typecheck && pnpm test` passes.
+- Manual check: start `scorel chat --cwd /tmp/scorel-fixture-foo-bar`; resulting connection reports `projectSlug: "tmp-scorel-fixture-foo-bar"`.
+
+## Tests
+
+- New unit tests `packages/daemon/src/projects/slug.test.ts` cover the rule cases above plus idempotence (`toProjectSlug(toProjectSlug(p))` is identity for clean inputs that contain no `-`).
+- Update `packages/daemon` integration / embedded daemon tests to construct with `workDir` and assert the emitted `projectSlug` matches the rule.
+- Update `apps/cli` tests where `EmbeddedDaemon` is instantiated.
+- Run `pnpm typecheck && pnpm test`.
+
+## Affected Paths
+
+- `packages/daemon/src/projects/slug.ts` (new)
+- `packages/daemon/src/projects/slug.test.ts` (new)
+- `packages/daemon/src/index.ts`
+- `packages/daemon/src/index.test.ts` (if present)
+- `apps/cli/src/index.ts`
+- `apps/cli/src/index.test.ts`
+- `docs/spec/daemon.md` (note the slug rule, point at `slug.ts`)
+- `docs/ROADMAP.md` (M5 step entry for S0031)
+
+## Risks And Boundaries
+
+- Hosts that previously fed exotic `projectSlug` values lose that hook. Acceptable: per S0026 the slug must be daemon-owned; no production caller relies on a non-path slug.
+- `-` collisions (`/pi-mono` vs `/pi/mono`) are accepted; daemon must never reverse a slug to derive identity. Display layer keeps `workDirHint` separately when displaying paths (introduced alongside `list_projects` in S0032, not S0031).
+- Windows: day-one rule is best-effort. If the project ever runs on native Windows, a follow-up spec hardens the rule; not blocking M5.
+- Slug changes if a project gets moved on disk. Acceptable v1: the daemon-side identity tracks current `workDir`; clients invalidate cache on new slug like any other identity change.