@chanlerdev/scorel 0.0.2 → 0.0.4

package/docs/spec/ship/S0090-gui-provider-delete-and-dark-code-theme.md

@@ -0,0 +1,77 @@
+# S0090: GUI Provider Delete And Dark Code Theme
+
+## Goal
+
+Fix two GUI regressions before the next IM expansion:
+
+- dark theme code blocks must use a dark Shiki theme instead of light-token colors;
+- Provider settings must expose a real delete path for configured providers.
+
+The business value is basic settings trust. Users should be able to remove bad provider config and read code blocks in the selected GUI theme.
+
+## Scope
+
+### Dark Code Blocks
+
+- Load both light and dark Shiki themes in the GUI code block highlighter.
+- Select the rendered theme from `:root[data-theme]` / system dark preference.
+- Re-render when the GUI theme changes.
+- Keep code block chrome styled by Scorel tokens; only syntax token colors switch.
+
+### Provider Delete
+
+- Add a protocol/client/daemon request for removing one provider from a project model profile.
+- Deleting a provider removes:
+  - `[providers.<id>]`;
+  - provider models owned by that provider;
+  - available models pointing at removed provider models;
+  - role selections that pointed at removed available models, with stable fallback when possible.
+- GUI Provider Settings exposes a delete button for the selected provider.
+- If no provider remains, the Provider page returns to the empty state without stale selected-provider UI.
+
+## Not In Scope
+
+- Deleting individual provider model definitions unless required by provider deletion.
+- Bulk reset of all model profile config.
+- Provider secret migration.
+- Changing provider catalog fetch behavior.
+- IM platform work; covered by S0091-S0093.
+
+## Acceptance Criteria
+
+- Dark GUI theme renders Shiki tokens with a dark theme.
+- Light GUI theme keeps the current light code block behavior.
+- Switching GUI theme updates future code block renders without app restart.
+- Provider delete removes the provider and all dependent model profile entries from persisted config.
+- Provider delete does not leave roles pointing at removed models.
+- GUI can delete the selected provider and updates the selected provider to the next available provider or empty state.
+- Remote GUI provider deletion uses the same daemon/client request as local GUI.
+
+## Testing Requirements
+
+- GUI Shiki tests prove both light and dark themes are loaded/selected.
+- Config renderer tests cover provider deletion and role fallback.
+- Protocol/client/daemon tests cover the delete request.
+- GUI render test covers delete button and empty-state transition.
+- Full `pnpm typecheck && pnpm test`.
+
+## Impacted Files
+
+- `apps/gui/src/renderer/chatbox/ShikiCodeBlock.tsx`
+- `apps/gui/src/renderer/chatbox/ShikiCodeBlock.test.tsx`
+- `apps/gui/src/shiki-theme.test.ts`
+- `apps/gui/src/renderer/settings/sections/ProviderSection.tsx`
+- `apps/gui/src/shared/ipc.ts`
+- `apps/gui/src/main.ts`
+- `apps/gui/src/main/local-host.ts`
+- `apps/gui/src/main/relay-service.ts`
+- `packages/protocol/src/events.ts`
+- `packages/protocol/src/wire.ts`
+- `packages/client/src/index.ts`
+- `packages/core/src/config/index.ts`
+- `packages/core/src/config/*.test.ts`
+- `packages/daemon/src/index.ts`
+
+## Status
+
+Done.

package/docs/spec/ship/S0091-built-in-qq-and-wechat-im-extensions.md

@@ -0,0 +1,125 @@
+# S0091: Built-In QQ And WeChat IM Extensions
+
+## Goal
+
+Add QQ Bot and WeChat as built-in IM extensions on the existing extension-backed channel bridge.
+
+The business value is channel reach. Telegram proved the bridge; QQ and WeChat force the adapter contract to stay generic enough for multiple IM platforms without forking Scorel runtime behavior.
+
+## Product Boundary
+
+Scorel must use official or documented bot/server APIs. This spec does not support personal-account reverse engineering, browser automation of consumer clients, unofficial Web WeChat scraping, or any path likely to get user accounts restricted.
+
+## Scope
+
+### Shared IM Adapter Utilities
+
+- Extract reusable helpers for HTTP polling/webhook-shaped adapters where the current Telegram code has platform-neutral logic.
+- Keep platform-specific authentication, payload parsing, mention rules, and send APIs inside each built-in extension.
+- Preserve the S0083 adapter boundary: adapters do platform IO only and never create sessions or write JSONL.
+
+### QQ Bot Extension
+
+Add:
+
+```text
+extensions/builtin/qq/
+  scorel.extension.json
+  adapter.js
+  adapter.d.ts
+  skills/qq/SKILL.md
+```
+
+Expected config shape:
+
+```toml
+[extensions.qq]
+enabled = true
+kind = "im"
+
+[extensions.qq.config]
+appId = "..."
+appSecret = "..."
+botId = "..."
+allowedConversationIds = "..."
+```
+
+QQ Bot uses the current official server-side credential flow: Scorel stores the developer-console `App ID` and `App Secret`, calls `https://bots.qq.com/app/getAppAccessToken`, caches the returned access token until shortly before expiry, and sends API requests with `Authorization: QQBot ACCESS_TOKEN`.
+
+`apiBaseUrl` and `accessTokenUrl` may remain internal override hooks for tests and sandbox work, but GUI Settings must not expose them as the default setup path.
+
+### WeChat Extension
+
+Add:
+
+```text
+extensions/builtin/wechat/
+  scorel.extension.json
+  adapter.js
+  adapter.d.ts
+  skills/wechat/SKILL.md
+```
+
+Expected config shape:
+
+```toml
+[extensions.wechat]
+enabled = true
+kind = "im"
+
+[extensions.wechat.config]
+webhookUrl = "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=..."
+callbackToken = "..."
+callbackHost = "127.0.0.1"
+callbackPort = 0
+```
+
+Use WeCom group robot webhook semantics for outbound send only. The user copies the full webhook URL from the official group robot configuration and pastes it into Scorel. This webhook cannot receive user messages from the group.
+
+Inbound WeChat receive is covered by S0094: Scorel can expose an official-account style plaintext callback server when `callbackToken` is configured. Do not make users split `key`, env var names, or base URLs in the default outbound setup path. Do not implement consumer WeChat personal account automation.
+
+### Skills
+
+Each built-in extension must include a platform-specific skill that tells the model:
+
+- what kind of conversation it is replying to;
+- how mentions/group context should be interpreted;
+- platform etiquette and short-response expectations;
+- when to use `SendChannelMessage`;
+- what not to assume about raw platform ids.
+
+## Not In Scope
+
+- Consumer QQ/WeChat personal account login.
+- Public callback deployment, TLS, or hosted ingress.
+- Rich media send support; covered by S0092.
+- GUI Settings layout; covered by S0093.
+- Remote Relay management of IM settings.
+
+## Acceptance Criteria
+
+- QQ and WeChat built-in extension manifests are discoverable by the existing loader.
+- Each extension starts only when explicitly enabled and required credentials are present.
+- QQ requires `appId` and `appSecret`; WeChat requires either a full outbound `webhookUrl` or an inbound `callbackToken`.
+- Each adapter normalizes incoming text messages into the existing `ImIncomingMessage` shape.
+- Each adapter sends plain text replies through the existing `SendChannelMessage` path.
+- QQ send obtains and reuses an official access token instead of accepting deprecated bot token config.
+- Adapter diagnostics redact secrets.
+- QQ, WeChat, Telegram, and loopback share the same channel bridge and session binding behavior.
+- No QQ/WeChat-specific branch is added to runtime/session/core channel orchestration.
+
+## Testing Requirements
+
+- Manifest loader coverage for QQ and WeChat built-ins.
+- Adapter normalization tests using local HTTP stubs or pure parser fixtures.
+- Send-message tests proving each adapter maps `SendChannelMessage` to its platform send API shape.
+- Secret redaction tests.
+- Full `pnpm typecheck && pnpm test`.
+
+## Local State Boundary
+
+Pre-1.0 local config may contain older `tokenEnv`, `token`, `webhookKeyEnv`, `webhookKey`, or `webhookBaseUrl` keys from earlier S0091 drafts. Those keys are no longer the supported setup surface. Users should re-enter QQ `App ID` / `App Secret` or WeChat `Outbound Webhook` / `Callback Token` in GUI Settings.
+
+## Status
+
+Done.

package/docs/spec/ship/S0092-im-message-media-and-human-cadence.md

@@ -0,0 +1,83 @@
+# S0092: IM Message Media And Human Cadence
+
+## Goal
+
+Make IM conversations feel alive and trustworthy by improving outgoing message capability and IM-specific response cadence.
+
+The business value is user confidence. In IM, silence for minutes reads as failure; Scorel needs visible progress and short human-style replies without compromising the existing agent loop.
+
+## Scope
+
+### SendChannelMessage Payload
+
+Extend `SendChannelMessage` from text-only to a structured outgoing message:
+
+```ts
+type SendChannelMessageInput = {
+  text?: string;
+  attachments?: Array<{
+    type: "image" | "file";
+    path?: string;
+    url?: string;
+    mimeType?: string;
+    caption?: string;
+  }>;
+  channel?: string;
+  target?: "current";
+};
+```
+
+Rules:
+
+- At least one of `text` or `attachments` is required.
+- Adapters may downgrade unsupported attachments to a clear tool error.
+- Local file paths must be explicit and must not be guessed from raw platform ids.
+- Tool result details report per-attachment status.
+
+### Adapter Capability Contract
+
+- Add optional adapter capabilities for outgoing attachment support.
+- Telegram/QQ/WeChat can initially support text and explicitly reject unsupported media.
+- Loopback should support structured capture of text and attachment metadata for tests.
+
+### IM System Prompt / Harness Guidance
+
+Add IM-specific guidance to channel context:
+
+- acknowledge quickly when work will take time;
+- send brief progress updates through `SendChannelMessage` during long tasks;
+- prefer concise, conversational wording;
+- do not wait until every tool finishes before sending any reply;
+- avoid exposing internal tool names unless useful to the user;
+- keep business-critical facts and file references precise.
+
+This guidance must enter through the existing channel harness item / skill path, not a second provider-level system prompt.
+
+## Not In Scope
+
+- Full media upload implementation for every platform.
+- Voice, stickers, albums, interactive buttons, or payments.
+- Cross-conversation proactive messages.
+- A new IM runtime loop or queue.
+- Fake progress timers outside the agent loop.
+
+## Acceptance Criteria
+
+- `SendChannelMessage` accepts text, image, and file attachment metadata.
+- Text-only calls remain backward compatible.
+- Unsupported attachment sends fail as tool errors, not silent no-ops.
+- IM channel reminders tell the agent to respond early and keep long-running users informed.
+- Built-in IM skills include platform-specific response cadence guidance.
+- Tests prove the model-facing tool schema rejects empty sends and preserves attachment metadata.
+
+## Testing Requirements
+
+- Core channel tool tests for structured payload parsing.
+- Loopback adapter tests for captured attachment metadata.
+- Telegram/QQ/WeChat tests for unsupported media errors or implemented send mapping.
+- Instruction/channel context tests for IM cadence guidance.
+- Full `pnpm typecheck && pnpm test`.
+
+## Status
+
+Done.

package/docs/spec/ship/S0093-gui-im-settings-platform-layout.md

@@ -0,0 +1,66 @@
+# S0093: GUI IM Settings Platform Layout
+
+## Goal
+
+Redesign GUI IM Settings so multiple platforms fit without crowding the page.
+
+The business value is scale. Telegram was one provider; Telegram + QQ + WeChat needs a repeatable platform row pattern where details expand only when the user asks.
+
+## Scope
+
+- Replace the current Telegram-only large form with a platform list.
+- Each platform row shows:
+  - platform name;
+  - enabled/disabled toggle;
+  - active/inactive status;
+  - concise credential/config summary;
+  - expand/collapse affordance.
+- Clicking a row expands its detailed config below that row.
+- Clicking the expanded row again collapses it.
+- The page defaults to all platforms collapsed unless a previous expanded platform is stored locally.
+- The last expanded platform is remembered locally; collapsing clears that remembered state.
+- Support Telegram, QQ, and WeChat using one reusable component shape.
+- Preserve existing Telegram config fields and persistence behavior.
+- Add QQ and WeChat config fields that match S0091/S0094.
+- For QQ and WeChat, expose the current quick setup fields only: QQ `App ID` / `App Secret`, WeChat `Outbound Webhook` plus inbound callback `Callback Token` / `Callback Host` / `Callback Port`.
+- Keep settings stored through the existing `getExtensionSettings` / `upsertExtensionSettings` IPC path.
+- Absorb immediate GUI review fixes found before push:
+  - expanded platform details must have a visible ownership boundary;
+  - the composer must not submit while an IME composition is active.
+
+## Not In Scope
+
+- Remote Relay IM settings.
+- Diagnostics timeline.
+- Live credential validation beyond existing adapter refresh behavior.
+- Account OAuth or QR login.
+
+## Acceptance Criteria
+
+- The IM Settings page renders three compact platform rows.
+- The first render does not expand Telegram by default.
+- No single disabled platform consumes a full settings page height.
+- Expanding Telegram reveals the existing credential/poll/allow-list fields.
+- Expanding QQ or WeChat reveals their S0091 config fields.
+- QQ and WeChat do not expose env-var-first credential fields in the default Settings flow.
+- Re-clicking the expanded platform collapses details.
+- Re-opening IM Settings restores the previously expanded platform when one was stored.
+- Toggling a platform writes the correct extension config and refreshes local Host IM extensions.
+- Direct secret fields are password inputs and are never displayed in summaries.
+- Layout remains readable in narrow GUI widths.
+- Expanded fields are visually grouped under the active platform, not blended into sibling platform rows.
+- Pressing Enter while Chinese/Japanese/Korean IME composition is active does not submit or block candidate selection.
+- Plain Enter still submits when enabled; Shift+Enter remains available for newline input.
+
+## Testing Requirements
+
+- GUI render tests for compact rows and expansion.
+- GUI interaction tests for default-collapsed, toggle-to-collapse, and stored expansion restore.
+- GUI interaction tests for toggling and field blur persistence.
+- Existing Telegram settings behavior remains covered.
+- GUI composer tests cover IME composition Enter, plain Enter, and Shift+Enter.
+- Full `pnpm typecheck && pnpm test`.
+
+## Status
+
+Done.

package/docs/spec/ship/S0094-im-inbound-runtime.md

@@ -0,0 +1,67 @@
+# S0094: IM Inbound Runtime
+
+## Goal
+
+Make built-in QQ and WeChat IM integrations actually receive user messages at runtime and route them through the shared Scorel IM session bridge.
+
+## Scope
+
+- Implement QQ Bot inbound receive through the official WebSocket Gateway.
+- Implement WeChat inbound receive through an official HTTP callback surface for official-account style plaintext text messages.
+- Keep WeCom group robot webhook as an outbound-only sender because that official webhook surface does not deliver user messages back to Scorel.
+- Keep adapters platform-IO only. They call `ctx.onMessage(...)`; daemon session creation stays in the existing IM bridge.
+- Update GUI settings and docs so outbound webhook configuration is not presented as if it enables inbound WeChat chat.
+
+## Not In Scope
+
+- Consumer personal WeChat reverse engineering, browser automation, or Web WeChat scraping.
+- Hosted public ingress, TLS certificates, relay tunneling, or automatic public URL provisioning.
+- Full WeChat encrypted callback decrypt/encrypt support. Plaintext callback is the S0094 receive baseline.
+- QQ sharding beyond one local gateway connection.
+
+## Acceptance Criteria
+
+- QQ adapter `start(ctx)` fetches an access token, fetches `/gateway`, opens a WebSocket, identifies with `QQBot <access_token>`, sends heartbeats, and calls `ctx.onMessage(...)` for text dispatch events normalized by `normalizeQQEvent`.
+- QQ adapter `stop()` closes the WebSocket and heartbeat timer.
+- WeChat adapter starts a local HTTP callback server when callback config is present, responds to GET URL verification, accepts text POST callbacks, normalizes them, and calls `ctx.onMessage(...)`.
+- WeChat adapter can still send outbound text to a configured WeCom group robot webhook; if only webhook URL is configured, inbound is explicitly not started.
+- Tests cover QQ gateway identify/heartbeat/dispatch/stop and WeChat callback verification/message routing.
+
+## Test Requirements
+
+- Add focused adapter tests before implementation.
+- Run:
+
+```bash
+pnpm --filter @scorel/daemon test -- qq-adapter.test.ts wechat-adapter.test.ts
+pnpm typecheck
+pnpm test
+```
+
+## Impacted Files
+
+- `extensions/builtin/qq/adapter.js`
+- `extensions/builtin/qq/adapter.d.ts`
+- `extensions/builtin/wechat/adapter.js`
+- `extensions/builtin/wechat/adapter.d.ts`
+- `packages/daemon/src/qq-adapter.test.ts`
+- `packages/daemon/src/wechat-adapter.test.ts`
+- `apps/gui/src/renderer/settings/sections/ImSection.tsx`
+- `docs/spec/ship/S0091-built-in-qq-and-wechat-im-extensions.md`
+
+## Risks And Boundaries
+
+- QQ event delivery also depends on the bot's platform-side event subscriptions and permissions. Scorel can connect to the gateway, but QQ may still omit events that are not enabled for the bot.
+- WeChat callback receive requires a URL Tencent can reach. Local-only callback ports are useful for tunnels and tests, but are not publicly reachable by themselves.
+- WeCom group robot webhook remains outbound-only by official product design; Scorel must not imply that it can receive user chat through that webhook.
+
+## References
+
+- QQ Bot event delivery and WebSocket gateway: <https://bot.q.qq.com/wiki/develop/api-v2/dev-prepare/interface-framework/event-emit.html>
+- QQ Bot gateway URL API: <https://bot.q.qq.com/wiki/develop/api-v2/openapi/wss/url_get.html>
+- WeCom group robot outbound webhook: <https://developer.work.weixin.qq.com/document/path/91770>
+- WeChat official account callback verification and normal messages: <https://developers.weixin.qq.com/doc/offiaccount/Basic_Information/Access_Overview.html>, <https://developers.weixin.qq.com/doc/offiaccount/Message_Management/Receiving_standard_messages.html>
+
+## Status
+
+Done.

package/docs/spec/ship/S0095-gui-im-session-list-refresh.md

@@ -0,0 +1,36 @@
+# S0095: GUI IM Session List Refresh
+
+## Goal
+
+Make GUI sidebars show IM sessions that are created in the background by Telegram, QQ, or WeChat inbound messages.
+
+## Scope
+
+- Notify GUI when the local Host creates a session, including IM sessions created in the background.
+- Refresh only the affected Project session list in response to that notification.
+- Keep IM session storage and Project binding unchanged.
+- Cover the selected/default IM workspace Project so background QQ/Telegram sessions appear without app restart.
+
+## Not In Scope
+
+- Changing where session JSONL files are stored.
+- Creating per-platform Projects.
+- Relay or hosted notification push for remote devices.
+
+## Acceptance Criteria
+
+- A GUI Project refreshes when the local Host reports a new session for that Project.
+- The refresh does not clear the active transcript.
+- Renderer test covers a background session appearing after initial load.
+
+## Test Requirements
+
+```bash
+pnpm --filter @scorel/app-gui test -- src/renderer/app-session-preload.test.tsx
+pnpm typecheck
+pnpm test
+```
+
+## Status
+
+Done.

package/docs/spec/ship/S0096-glob-stable-order.md

@@ -0,0 +1,32 @@
+# S0096: Glob Stable Order
+
+## Goal
+
+Make the `Glob` tool return deterministic results across local macOS and Linux CI.
+
+## Scope
+
+- Sort `Glob` file results by workspace-relative path before applying `head_limit` / `offset`.
+- Preserve existing `Grep` behavior and pagination shape.
+
+## Not In Scope
+
+- Changing ripgrep invocation.
+- Changing Grep content/count ordering.
+
+## Acceptance Criteria
+
+- `Glob` result limiting does not depend on filesystem or ripgrep output order.
+- Existing coding tool tests pass on Linux and macOS.
+
+## Test Requirements
+
+```bash
+pnpm --filter @scorel/core test -- src/tools/coding-tools.test.ts
+pnpm typecheck
+pnpm test
+```
+
+## Status
+
+Done.

package/docs/spec/ship/S0097-rtk-token-saving-settings.md

@@ -0,0 +1,61 @@
+# S0097: RTK Token Saving Settings
+
+## Goal
+
+Add an opt-in GUI setting that enables RTK-backed token saving for Scorel Bash tool execution without changing session replay, model prompts, or existing tool input contracts.
+
+RTK here means Rust Token Killer: a CLI command rewriter/filter that compresses shell command output before it reaches the LLM context.
+
+## Scope
+
+- Add device-scoped `[runtime] tokenSavingRtk = boolean` config.
+- Add GUI Settings page `Token 节省` with an RTK enable toggle and status.
+- When the user enables the setting, Host ensures the `rtk` binary is available:
+  - first detect `rtk` on PATH;
+  - if missing on macOS/Linux with Homebrew available, attempt `brew install rtk`;
+  - if install fails, keep the setting but report RTK as unavailable.
+- Bash tool execution and RTK discovery use the user's default shell path (`options.defaultShell` where provided, then `SHELL`, then OS user shell, then `/bin/sh` fallback), not a hard-coded `/bin/bash`.
+- Shell invocation preserves the command string and uses shell-compatible command flags (`-lc` for sh/bash/zsh-like shells, `-c` for csh/tcsh/fish-like shells).
+- When enabled and available, the Bash tool asks RTK to rewrite the original command and executes the rewritten command, while preserving the original tool input contract and cwd semantics.
+- Bash tool result details expose RTK application state plus estimated output/saved tokens for Scorel-owned UI/diagnostics.
+- Runtime Settings summarizes RTK token savings from a maintained Scorel runtime stats file across projects on the current host.
+- Chat transcript rendering continues to display the original Bash tool-call command, not the RTK rewritten execution command.
+- Session JSONL and persistent events keep the same tool result shape; no prompt or input assembly contract changes.
+
+## Not In Scope
+
+- Changing model message assembly.
+- Compressing Read / Grep / Glob built-in tool results.
+- Provider-specific token accounting.
+- A per-session savings breakdown view.
+- Global shell hook installation through `rtk init`.
+- Silent install at app startup.
+
+## Acceptance Criteria
+
+- `tokenSavingRtk = false` keeps Bash behavior equivalent to the current path.
+- `tokenSavingRtk = true` uses RTK rewrite for Bash command execution when RTK is available, without changing the tool-call input command string.
+- Tool results sent back into model context include only the user-visible content, not RTK execution metadata or rewritten command details.
+- GUI Bash tool blocks display the original tool-call command even when RTK rewrites the command at execution time.
+- RTK detection and first-enable install checks run in the same default shell environment as command execution, so zsh-configured PATH entries are visible.
+- Runtime creation resolves the RTK executable whenever `tokenSavingRtk` is enabled, so saved settings affect actual Bash tool execution, not only the Settings UI.
+- Runtime Settings token totals come from Scorel-maintained RTK stats updated when Scorel persists tool results, so other agents' RTK usage in the same project is not counted.
+- GUI Settings can enable/disable RTK token saving and shows available/unavailable status.
+- Config parsing rejects unknown `[runtime]` keys.
+- RTK install is only attempted after the user enables the setting.
+- Existing tests, typecheck, and full test suite pass.
+
+## Test Requirements
+
+```bash
+pnpm --filter @scorel/core test -- src/config/config.test.ts src/tools/coding-tools.test.ts
+pnpm --filter @scorel/daemon test -- src/embedded/embedded.test.ts
+pnpm --filter @scorel/app-gui test -- src/renderer/gui-shell.test.tsx
+pnpm verify:m9-gui # service-level local/relay plus Electron CDP settings + prompt smoke
+pnpm typecheck
+pnpm test
+```
+
+## Status
+
+Done.

package/docs/spec/ship/S0098-local-daemon-singleton-unified-state.md

@@ -0,0 +1,96 @@
+# S0098: Local Daemon Singleton And Unified State
+
+## Goal
+
+Make the local Scorel Host a single user-level daemon with one local state root, so CLI, GUI, WebUI, IM, and Relay clients attach to the same Project registry, Session JSONL, runtime stats, and config.
+
+## Scope
+
+- Use `~/.scorel` as the only local Host state root:
+  - `daemon.json`
+  - `projects.json`
+  - `sessions/*.jsonl`
+  - `runtime-stats.json`
+  - `config.toml`
+  - `gui-store.json`
+- Remove GUI-local Host state ownership:
+  - no new `~/.scorel/gui/projects.json`;
+  - no new `~/.scorel/gui/sessions`;
+  - GUI still has GUI UI state, but it lives at `~/.scorel/gui-store.json`.
+- Add `scorel host start`, a background daemon start path that starts the singleton local daemon without tying daemon lifetime to the CLI process that launched it.
+- Make local GUI attach to the singleton daemon when available.
+- Make local GUI start the singleton daemon in the background when no live daemon exists, then attach to it.
+- Make `scorel up` ensure the singleton daemon is running, register the current cwd as a Project, and launch/serve UI without owning daemon lifetime.
+- Keep foreground `scorel host serve` for debugging; Ctrl-C on foreground serve still stops that foreground process.
+- Daemon lifecycle:
+  - daemon is not killed when one client exits;
+  - explicit `scorel host stop` stops it;
+  - if no IM extensions are active, daemon idle-shuts down after no connected clients and no active work for the configured timeout;
+  - if any IM extension is active, daemon remains alive until explicit stop.
+
+## Not In Scope
+
+- Migrating old `~/.scorel/gui/projects.json` or `~/.scorel/gui/sessions` into the unified state. Scorel is pre-1.0; users may remove old GUI-local files manually if needed.
+- System LaunchAgent/login-item installation.
+- Multi-user or system-wide daemon.
+- Remote daemon lifecycle changes.
+- Per-session RTK stats breakdown UI.
+- Restart-on-crash supervisor.
+
+## Acceptance Criteria
+
+- GUI local Projects and Sessions are created under `~/.scorel/projects.json` and `~/.scorel/sessions`, not under `~/.scorel/gui`.
+- `gui-store.json` is stored at `~/.scorel/gui-store.json`.
+- `scorel host start` starts or reuses a background singleton daemon and returns without waiting for daemon shutdown.
+- `scorel up` reuses an existing running daemon instead of spawning a child daemon that dies with `scorel up`.
+- Starting GUI when a daemon is alive attaches to it and does not start a second Host writer.
+- Starting GUI when no daemon is alive starts the background singleton daemon, then attaches to it.
+- If no clients remain, no work is active, and no IM extension is active, daemon exits after its idle timeout.
+- If an IM extension is active, daemon does not idle-exit solely because there are no GUI/CLI clients.
+- Model/tool messages remain unchanged: daemon lifecycle and state unification do not alter tool call args or provider tool result context.
+
+## Test Requirements
+
+```bash
+pnpm --filter @scorel/app-cli test -- src/daemon-cli.test.ts src/up-cli.test.ts
+pnpm --filter @scorel/app-gui test -- src/main/local-host.test.ts
+pnpm --filter @scorel/daemon test -- src/embedded/embedded.test.ts
+pnpm verify:m9-gui
+pnpm typecheck
+pnpm test
+```
+
+Manual/E2E:
+
+- Start GUI from a clean temp HOME through Electron CDP.
+- Verify local Project registration creates `~/.scorel/projects.json`.
+- Verify local Session creation creates `~/.scorel/sessions/*.jsonl`.
+- Verify no `~/.scorel/gui/projects.json` or `~/.scorel/gui/sessions` is created.
+- Verify GUI start from a clean HOME creates `~/.scorel/daemon.json` and attaches to that daemon.
+- Verify `scorel host start` returns while `scorel host status` still reports a running daemon.
+- Verify `scorel up` exit does not stop the singleton daemon it started.
+- Verify short idle timeout stops a daemon with no clients and no active IM.
+- Verify active IM prevents idle shutdown.
+
+## Impacted Files
+
+- `apps/cli/src/daemon-cli.ts`
+- `apps/cli/src/up-cli.ts`
+- `apps/cli/src/index.ts`
+- `apps/gui/src/main.ts`
+- `apps/gui/src/main/local-host.ts`
+- `packages/daemon/src/index.ts`
+- `scripts/verify-m9-gui-cdp-e2e.ts`
+- `docs/SHIP.md`
+- `docs/ROADMAP.md`
+
+## Risks And Boundaries
+
+- Background daemon process management must not leave stale `daemon.json` as a false-positive running daemon.
+- The singleton daemon must remain the only local writer for Project and Session files.
+- Electron GUI starts the daemon through the CLI entrypoint; packaged builds must provide `SCOREL_CLI_ENTRYPOINT` when the source tree is unavailable.
+- Old GUI-local state under `~/.scorel/gui` is intentionally not migrated in this spec.
+
+## Status
+
+Done.