@chanlerdev/scorel 0.0.1

package/docs/spec/ship/S0007-cli-alpha.md

@@ -0,0 +1,49 @@
+# S0007: CLI Alpha
+
+## Goal
+
+Expose the M1 product experience: `scorel chat` starts the embedded path, streams assistant output, and resumes a persisted local session.
+
+## Deliverable
+
+- `scorel chat` command in `apps/cli`.
+- Local session create/resume behavior.
+- Prompt input loop for minimal multi-turn chat.
+- Streaming assistant output.
+- Basic status/error output.
+- Real provider runtime path for manual/product validation.
+
+## Success Criteria
+
+- A user can run `scorel chat`, send multiple prompts, see assistant output, exit, and continue the same session.
+- CLI uses `@scorel/client` plus embedded daemon wiring; it does not call runtime/session directly.
+- Session files are written through daemon-owned persistence.
+- The CLI remains simple enough to replace with TUI/WebUI later without moving domain logic into the app.
+
+## Boundaries
+
+- No slash command suite.
+- No remote `attach`.
+- No standalone daemon command behavior beyond entrypoint shell if already created.
+- No checkpoint, rewind, compact, permission, MCP management, or GUI.
+- No polished TUI. Plain terminal interaction is enough.
+
+## Verification
+
+- `pnpm --filter @scorel/app-cli test`
+- End-to-end validation runs CLI against a real provider and verifies multi-turn persistence.
+- `pnpm -r typecheck`
+- `pnpm -r test`
+
+## Affected Paths
+
+- `apps/cli/`
+- `packages/client/`
+- `packages/daemon/`
+- `packages/core/`
+- `packages/protocol/`
+
+## Risks
+
+- Putting UX shortcuts directly into CLI can bypass daemon/client and invalidate the architecture.
+- Mock-only validation can make the CLI look complete while no real model can run. Keep deterministic unit coverage, but product completion requires real-provider validation.

package/docs/spec/ship/S0008-coding-tools.md

@@ -0,0 +1,107 @@
+# S0008: File And Shell Coding Tools
+
+## Goal
+
+Expose the first coding-agent tool surface through the existing runtime, daemon, client, and CLI path: `Read`, `Write`, `Edit`, and `Bash`.
+
+This is M2.1. It makes `scorel chat` capable of reading files, editing files, writing files, and running verification commands in a real workspace. Search tools and Todo are intentionally separate follow-up specs.
+
+## Deliverable
+
+- Built-in `Read` tool.
+- Built-in `Write` tool.
+- Built-in `Edit` tool.
+- Built-in `Bash` tool.
+- Tool registration path for the default `coding` preset.
+- Runtime loop support for emitting tool call and tool result messages through daemon/client events.
+- Session persistence for tool calls and tool results.
+- CLI-visible tool progress / result output that is plain and debuggable.
+
+## Tool Semantics
+
+### `Read`
+
+- Reads a file from the local filesystem.
+- Accepts an absolute or cwd-relative file path; paths resolve under the CLI working directory unless absolute.
+- Does not read directories.
+- Supports `offset` and `limit` by line.
+- Returns content with stable 1-based line numbers.
+- Fails predictably for missing files, directories, unreadable files, and oversized reads that require `offset` / `limit`.
+- Records enough read state for `Write` / `Edit` stale checks.
+
+### `Write`
+
+- Creates a new file or fully rewrites a file.
+- Existing files must be read first in the current session before `Write`.
+- If the file changes after the recorded read, `Write` must fail instead of overwriting.
+- Prefer `Edit` for normal modifications to existing files.
+- Creates parent directories only when explicitly requested by args or implementation contract; do not silently create broad directory trees.
+
+### `Edit`
+
+- Performs exact string replacement.
+- Existing files must be read first in the current session before `Edit`.
+- If the file changes after the recorded read, `Edit` must fail instead of applying stale changes.
+- `old_string` must match exactly once unless `replace_all` is true.
+- `old_string === new_string`, missing matches, and ambiguous matches must fail with clear tool-result errors.
+- Creating new files through `Edit` is not required for M2; use `Write`.
+
+### `Bash`
+
+- Executes a command in a specified cwd.
+- Has a default timeout and a hard maximum timeout.
+- Truncates large stdout/stderr while preserving exit code and enough diagnostic tail.
+- Returns non-zero exits as tool results, not thrown runtime failures.
+- Is for commands, tests, builds, git status, and project scripts.
+- Must not be encouraged as the primary path for reading or editing files; use `Read`, `Write`, and `Edit`.
+
+## Scope
+
+- Keep tools in `@scorel/core`.
+- Keep execution owned by runtime / daemon, not CLI.
+- Keep CLI as an entrypoint that displays events.
+- Keep tool errors as data visible to the model and user.
+
+## Not In Scope
+
+- Snapshot-based recovery.
+- Permission approval UI or policy.
+- Sandbox execution.
+- `Grep`, `Glob`, `Todo`, `LS`, notebook editing, image/PDF reading.
+- MCP tool loading.
+- Remote daemon or reconnect semantics beyond existing M1 path.
+- Rewind / compact / cancel / steer / followUp UX.
+
+## Acceptance Criteria
+
+- `scorel chat` can use the built-in tools through the daemon/client path.
+- A real-provider smoke can trigger `Read`, `Write`, `Edit`, and `Bash` through model tool calls.
+- Tool call and tool result events are persisted in JSONL and restored into context.
+- `Write` and `Edit` reject existing-file changes when the file was not read first.
+- `Write` and `Edit` reject stale writes after external file modification.
+- `Edit` rejects missing and ambiguous `old_string` matches.
+- `Bash` enforces timeout and output truncation.
+- CLI-facing code does not import session/runtime internals directly.
+
+## Verification
+
+- `pnpm --filter @scorel/core test -- tools`
+- `pnpm --filter @scorel/daemon test`
+- `pnpm --filter @scorel/client test`
+- `pnpm --filter @scorel/app-cli test`
+- `pnpm typecheck && pnpm test`
+
+## Affected Paths
+
+- `packages/core/src/tools/`
+- `packages/core/src/runtime/`
+- `packages/daemon/`
+- `packages/client/`
+- `apps/cli/`
+- `packages/protocol/src/`
+
+## Risks
+
+- Overbuilding Bash permissions will stall M2. Use minimal local execution constraints first: cwd, timeout, truncation, and structured errors.
+- Letting Bash replace file tools will make edits harder to inspect and test. Tool descriptions must strongly prefer `Read` / `Write` / `Edit` for file operations.
+- Skipping stale checks on `Write` / `Edit` can overwrite user edits. Pre-read state is mandatory for existing-file writes.

package/docs/spec/ship/S0009-code-discovery-tools.md

@@ -0,0 +1,82 @@
+# S0009: Code Discovery Tools
+
+## Goal
+
+Expose structured code discovery tools through the existing runtime, daemon, client, and CLI path: `Glob` and `Grep`.
+
+This is M2.2. It keeps common code search out of ad hoc shell output so tool results are easier to display, persist, replay, and summarize.
+
+## Deliverable
+
+- Built-in `Glob` tool.
+- Built-in `Grep` tool.
+- Tool registration in the default `coding` preset.
+- Tool registration in the `readonly` preset.
+- Structured result shape for matched paths and content hits.
+- CLI-visible search progress / result output that is compact and debuggable.
+
+## Tool Semantics
+
+### `Glob`
+
+- Finds files by glob pattern under a cwd.
+- Returns stable, normalized paths.
+- Sorts results predictably.
+- Enforces a maximum result count.
+- Fails predictably for invalid patterns and inaccessible cwd.
+
+### `Grep`
+
+- Searches file contents using ripgrep-compatible semantics.
+- Supports regex patterns.
+- Supports glob/type filtering when practical.
+- Supports output modes for matching files and matching lines.
+- Enforces maximum result count and output size.
+- Fails predictably for invalid regex, inaccessible cwd, and missing ripgrep.
+
+## Scope
+
+- Keep search tools in `@scorel/core`.
+- Keep execution owned by runtime / daemon, not CLI.
+- Persist tool calls and tool results in session JSONL.
+- Keep errors as tool-result data visible to the model and user.
+
+## Not In Scope
+
+- Full file indexing.
+- LSP symbol search.
+- Web search.
+- Directory listing as a standalone `LS` tool.
+- MCP search tools.
+
+## Acceptance Criteria
+
+- `scorel chat` can use `Glob` and `Grep` through the daemon/client path.
+- A real-provider smoke can trigger both tools through model tool calls.
+- `Glob` returns stable path lists and respects result limits.
+- `Grep` returns structured matches and respects result/output limits.
+- Tool calls and results are persisted in JSONL and restored into context.
+- CLI-facing code does not import session/runtime internals directly.
+
+## Verification
+
+- `pnpm --filter @scorel/core test -- tools`
+- `pnpm --filter @scorel/daemon test`
+- `pnpm --filter @scorel/client test`
+- `pnpm --filter @scorel/app-cli test`
+- `pnpm typecheck && pnpm test`
+
+## Affected Paths
+
+- `packages/core/src/tools/`
+- `packages/core/src/runtime/`
+- `packages/daemon/`
+- `packages/client/`
+- `apps/cli/`
+- `packages/protocol/src/`
+
+## Risks
+
+- If `Grep` just wraps arbitrary shell text, search results will be hard to display and replay. Keep the output structured.
+- If result limits are missing, a large repository can flood the session context.
+- If Bash remains the preferred search route, the model will learn the wrong tool habit.

package/docs/spec/ship/S0010-todo-tool-and-cli.md

@@ -0,0 +1,81 @@
+# S0010: Todo Tool And CLI
+
+## Goal
+
+Expose a normal Todo List tool and make Todo state changes visible in the CLI.
+
+This is M2.3. It gives coding sessions a lightweight progress backbone without introducing plan mode, subagents, or workflow orchestration.
+
+## Deliverable
+
+- Built-in `Todo` tool.
+- Todo item model with `id`, `content`, and `status`.
+- Supported statuses: `pending`, `in_progress`, `completed`.
+- Replace/update semantics for the current session's Todo list.
+- Session persistence for Todo state changes.
+- Daemon/client events for Todo changes.
+- CLI rendering for the current Todo list and status transitions.
+
+## Tool Semantics
+
+### `Todo`
+
+- Maintains a session-scoped Todo list.
+- Creates, updates, reorders, and deletes Todo items.
+- Allows at most one `in_progress` item at a time.
+- Treats Todo changes as structured state, not free-form assistant text.
+- Emits clear errors for invalid ids, invalid statuses, duplicate `in_progress` items, and malformed updates.
+
+## CLI Semantics
+
+- CLI displays Todo list changes when they happen.
+- CLI shows status transitions clearly enough for the user to understand current progress.
+- CLI output stays plain terminal text; no TUI is required.
+- Resume should reconstruct the latest Todo state from session JSONL.
+
+## Scope
+
+- Keep Todo state session-scoped.
+- Keep Todo owned by runtime / daemon, not CLI-local memory.
+- Persist Todo changes in JSONL.
+- Keep Todo visible to the user and available to the model as useful context.
+
+## Not In Scope
+
+- Plan mode.
+- Dependencies between Todo items.
+- Owners, teams, subagents, or delegation.
+- Cross-session Todo storage.
+- Calendar/reminder automation.
+
+## Acceptance Criteria
+
+- `scorel chat` can use `Todo` through the daemon/client path.
+- Todo changes are persisted in JSONL and restored on resume.
+- CLI visibly updates when Todo items are created, completed, deleted, or moved to `in_progress`.
+- Invalid Todo updates return structured tool-result errors.
+- A test verifies that two items cannot both be `in_progress`.
+- CLI-facing code does not import session/runtime internals directly.
+
+## Verification
+
+- `pnpm --filter @scorel/core test -- todo`
+- `pnpm --filter @scorel/daemon test`
+- `pnpm --filter @scorel/client test`
+- `pnpm --filter @scorel/app-cli test`
+- `pnpm typecheck && pnpm test`
+
+## Affected Paths
+
+- `packages/core/src/tools/`
+- `packages/core/src/runtime/`
+- `packages/daemon/`
+- `packages/client/`
+- `apps/cli/`
+- `packages/protocol/src/`
+
+## Risks
+
+- If Todo is only assistant text, resume and UI state become unreliable. Store it as structured session state.
+- If Todo becomes a workflow engine, M2 will stall. Keep it to a plain list.
+- If CLI hides Todo changes, the user loses trust in long-running coding tasks.

package/docs/spec/ship/S0011-coding-agent-alpha-smoke.md

@@ -0,0 +1,110 @@
+# S0011: Coding Agent Alpha Smoke
+
+## Goal
+
+Validate M2 as a complete Coding Agent Alpha rather than a collection of isolated tools.
+
+This is M2.4. It proves `scorel chat` can complete a small coding task in a real temporary repository using search, read, edit/write, bash verification, Todo progress, session persistence, and resume.
+
+## Deliverable
+
+- End-to-end real-provider coding smoke test.
+- Strict config schema for pi-ai builtin/custom model selection.
+- Fixed Scorel user root and session path: `~/.scorel` and `~/.scorel/sessions`.
+- Temporary repository fixture with source files and a test command.
+- Scripted task that requires `Glob` or `Grep`, `Read`, `Edit` or `Write`, `Bash`, and `Todo`.
+- Assertions for CLI-visible tool output and Todo status changes.
+- Assertions that tool calls, tool results, and Todo state persist to JSONL.
+- Resume assertion that the latest context includes prior tool results and Todo state.
+
+## Scenario
+
+The smoke should use a small real workspace, for example:
+
+1. User asks Scorel to fix a failing function.
+2. Model creates a Todo list.
+3. Model uses `Grep` or `Glob` to find the target file.
+4. Model uses `Read` to inspect the file.
+5. Model uses `Edit` or `Write` to change it.
+6. Model uses `Bash` to run the relevant test.
+7. Model marks Todo items complete.
+8. CLI output shows tool calls, command result, and Todo transitions.
+9. Session JSONL can be loaded again and used for resume.
+
+## Scope
+
+- Use pi-ai for real provider protocol handling in product validation.
+- Keep fixed product paths out of config; config only covers variable model/provider settings.
+- Keep pi-ai builtin models and custom compatible endpoints as separate config branches.
+- Verify the full daemon/client/CLI path.
+- Keep the fixture small and fast.
+- Treat this spec as M2 completion proof.
+
+## Not In Scope
+
+- Mock-only or scripted fake-provider validation as completion proof.
+- Broad benchmark suite.
+- Permission approval, sandbox, checkpoint, remote daemon, MCP, GUI.
+- Complex multi-file refactors.
+
+## Acceptance Criteria
+
+- The end-to-end smoke fails before the integrated real-provider M2 path is complete.
+- The smoke passes after S0008, S0009, and S0010 are implemented.
+- CLI output includes visible Todo transitions and tool progress/result output.
+- JSONL contains the expected user message, assistant/tool events, and Todo state changes.
+- Resume loads enough context for the model to continue from the completed task.
+- `pnpm typecheck && pnpm test` passes.
+
+## Config Shape
+
+Builtin pi-ai model:
+
+```toml
+[model]
+type = "builtin"
+provider = "openai"
+id = "gpt-5.4-mini"
+apiKeyEnv = "SCOREL_API_KEY"
+```
+
+Custom compatible endpoint:
+
+```toml
+[model]
+type = "custom"
+api = "openai-completions"
+provider = "chanleramp"
+id = "gpt-5.4-mini"
+baseUrl = "https://amp.chanler.dev/v1"
+apiKeyEnv = "SCOREL_API_KEY"
+contextWindow = 400000
+maxTokens = 128000
+reasoning = true
+```
+
+Supported custom `api` values for M2 are `openai-completions`, `openai-responses`, `google-generative-ai`, and `anthropic-messages`.
+
+## Verification
+
+- `pnpm --filter @scorel/app-cli test -- coding-agent-alpha`
+- `pnpm --filter @scorel/core test -- tools`
+- `pnpm --filter @scorel/daemon test`
+- `pnpm --filter @scorel/client test`
+- `pnpm typecheck && pnpm test`
+
+## Affected Paths
+
+- `apps/cli/`
+- `apps/cli/src/index.test.ts`
+- `packages/core/src/tools/`
+- `packages/core/src/runtime/`
+- `packages/daemon/`
+- `packages/client/`
+- `packages/protocol/src/`
+
+## Risks
+
+- A smoke that only checks isolated tool calls will not prove product value. It must go through CLI-visible daemon/client flow.
+- A mock-only smoke can hide the product failure mode where `scorel chat` cannot actually call an LLM. Completion proof must include a real provider run.
+- If resume is skipped, Scorel loses its product distinction from a disposable coding chat.

package/docs/spec/ship/S0012-coding-tools-maturity.md

@@ -0,0 +1,143 @@
+# S0012: Coding Tools Maturity
+
+## Goal
+
+Mature the M2 coding tool surface by aligning the contracts with Claude Code / pi-coding-agent style behavior while keeping the current daemon/client/runtime path unchanged.
+
+This is a tool-semantics hardening spec, not a checkpoint, sandbox, permission UI, LSP, subagent, or remote daemon spec.
+
+## Deliverable
+
+- Replace `Todo` with `TodoWrite`.
+- Keep the user-visible tool set to `Read` / `Write` / `Edit` / `Bash` / `Glob` / `Grep` / `TodoWrite`.
+- Harden `Read` state so writes require complete coverage of the current file version.
+- Truncate long default `Read` results and report returned line count, total line count, truncation, and continuation offset.
+- Harden `Write` as full-file create/update with pre-read coverage and stale checks for existing files.
+- Harden `Edit` as exact single replacement with pre-read coverage and stale checks.
+- Move `Glob` and `Grep` to ripgrep-backed implementations.
+- Keep tool errors visible as tool results through the existing runtime/daemon/client path.
+- Update pi-ai tool schemas and CLI smoke to use `TodoWrite`.
+
+## Tool Semantics
+
+### `Read`
+
+- Arguments: `file_path`, `offset?`, `limit?`, `full?`.
+- Reads one file from the local workspace.
+- Supports `offset` and `limit`.
+- Defaults to returning at most 2,000 complete lines.
+- Also enforces a dynamic output budget of 1% of the current model context window by removing whole lines from the end of the result.
+- `full: true` uses a larger 10% context-window budget.
+- If no model context window is available, the fallback context window is 200,000 tokens.
+- Token usage is estimated on the line-numbered tool result text, conservatively as roughly one token per three characters until a model tokenizer is available.
+- Never truncates inside a line. If one line exceeds the output budgets, `Read` fails instead of returning a partial line.
+- Returns `startLine`, `endLine`, `totalLines`, `truncated`, `nextOffset`, `canWrite`, `estimatedTokens`, and `tokenBudget`.
+- Returns stable 1-based line numbers.
+- Rejects binary files and document/media types that are not yet supported by a dedicated reader path.
+- Read ranges are accumulated for the current file version.
+- `canWrite` becomes true once the accumulated ranges cover the full current file.
+- Truncated reads do not unlock `Write` / `Edit` until follow-up reads cover the remaining lines.
+- `full: true` requests the full file and cannot be combined with `offset` or `limit`; it is still subject to the 10% dynamic token budget.
+- Directories fail with a hint to use `Glob`.
+
+### `Write`
+
+- Arguments: `file_path`, `content`.
+- Creates new files without a prior read.
+- Updating existing files requires prior read coverage of the full current file.
+- Updating existing files fails if the file changed since the read.
+- Writes are full-file replacements.
+- Successful writes update the read snapshot to the new full content.
+- Model-facing result is lightweight: success text plus `type`, `filePath`, and `bytes`; full old/new contents are not returned.
+
+### `Edit`
+
+- Arguments: `file_path`, `old_string`, `new_string`, `replace_all?`.
+- Requires prior read coverage of the full current file.
+- Fails if the file changed since read.
+- Fails if `old_string === new_string`.
+- Fails if `old_string` is missing.
+- Fails if `old_string` matches multiple times unless `replace_all` is true.
+- Successful edits update the read snapshot to the new full content.
+- Model-facing result is lightweight: success text plus file path and replacement counts; full diffs and file contents are reserved for UI/event metadata.
+
+### `Bash`
+
+- Arguments: `command`, `cwd?`, `timeout?`, `maxOutputBytes?`, `description?`.
+- Runs in the workspace or a workspace subdirectory.
+- Enforces timeout and output truncation.
+- Non-zero exits return tool results, not runtime crashes.
+- Timeout returns a tool error visible to the model.
+
+### `Glob`
+
+- Arguments: `pattern`, `path?`, `head_limit?`, `offset?`.
+- Uses ripgrep file discovery (`rg --files`) plus `--glob` filters.
+- Defaults to current workspace when `path` is omitted.
+- Returns relative file paths.
+- Applies pagination and truncation metadata.
+
+### `Grep`
+
+- Arguments: `pattern`, `path?`, `glob?`, `output_mode?`, `-B?`, `-A?`, `-C?`, `context?`, `-n?`, `-i?`, `type?`, `head_limit?`, `offset?`, `multiline?`.
+- Uses ripgrep for content search.
+- Default `output_mode` is `files`.
+- Supports `content`, `files`, and `count`.
+- Adds result limits by default.
+- Uses ripgrep `--max-columns 500` to avoid noisy minified/base64 lines.
+- Returns relative paths and pagination metadata.
+
+### `TodoWrite`
+
+- Arguments: complete `todos` array.
+- Each todo has `content`, `status`, and optional `activeForm`.
+- Status is `pending`, `in_progress`, or `completed`.
+- Allows at most one `in_progress`.
+- Replaces the session todo list as a whole.
+- If all provided todos are `completed`, the stored current list becomes empty.
+- Result includes only `oldTodos` and `currentTodos`; a text reminder may explain automatic clearing.
+
+## Not In Scope
+
+- `MultiEdit`.
+- Permission approval UI.
+- Sandbox execution.
+- Checkpoint / rollback.
+- LSP.
+- Background Bash / monitor.
+- Web tools.
+- MCP tool loading.
+
+## Acceptance Criteria
+
+- `TodoWrite` is registered and exposed to pi-ai instead of `Todo`.
+- `TodoWrite` returns old/current todo lists and clears stored current todos when all requested todos are completed.
+- Default `Read` truncates long files by complete lines and returns the current line range and total line count.
+- `Read` enforces line and dynamic estimated-token budgets without returning partial lines.
+- `Read` rejects binary/document/media files until dedicated readers are implemented.
+- Partial reads can unlock `Write` or `Edit` only after their accumulated ranges cover the full current file.
+- Any covered read unlocks `Write` and `Edit` only while the file is unchanged.
+- `Write` creates new files without pre-read and updates existing files only after complete read coverage.
+- `Edit` rejects missing, ambiguous, unchanged, stale, and incomplete-coverage edits.
+- `Write` and `Edit` do not return full file contents in model-facing tool results.
+- `Glob` returns ripgrep-backed file results with pagination metadata.
+- `Grep` returns ripgrep-backed search results for `files`, `content`, and `count`.
+- CLI smoke uses `TodoWrite` and still verifies search, read, edit, bash, persistence, and resume.
+- `pnpm --filter @scorel/core test -- tools`
+- `pnpm --filter @scorel/app-cli test -- coding-agent-alpha`
+- `pnpm typecheck && pnpm test` or equivalent per-package commands pass.
+
+## Affected Paths
+
+- `packages/core/src/tools/coding-tools.ts`
+- `packages/core/src/tools/coding-tools.test.ts`
+- `packages/core/src/provider/pi-ai.ts`
+- `apps/cli/src/index.test.ts`
+- `docs/spec/tools.md`
+- `docs/ROADMAP.md`
+
+## Risks
+
+- Ripgrep availability can fail outside developer machines. Return a clear tool error instead of falling back to slow ad hoc scanning.
+- Renaming `Todo` to `TodoWrite` changes model-facing tool calls and tests; keep this as S0012 rather than mixing with unrelated features.
+- Coverage-based write unlocks is more complex than Claude Code's partial-view rejection; keep tests focused on stale detection and full-file coverage so long-file pagination does not become unsafe.

package/docs/spec/ship/S0013-local-daemon-protocol.md

@@ -0,0 +1,57 @@
+# S0013: Local Daemon Protocol
+
+## Goal
+
+Prepare the protocol and package boundaries needed for M3 local daemon work without starting a real background process yet.
+
+This spec turns the existing embedded-only daemon/client path into a transport-ready contract for local standalone daemon work.
+
+## Scope
+
+- Align `@scorel/protocol` wire types with M3 local daemon needs.
+- Define the Node-only socket transport surface as a client subpath contract.
+- Keep `@scorel/client` browser-safe at its root export.
+- Add tests that protect `@scorel/client` from importing `@scorel/core`, `@scorel/daemon`, or Node-only socket modules through the root export.
+- Add daemon-side tests for connect, subscribe, resync, and per-session `lastSeq` behavior through the protocol interface.
+- Document any small contract changes in `docs/spec/client.md` or `docs/spec/daemon.md` if the implementation changes public names.
+
+## Not In Scope
+
+- A standalone `scorel daemon start` process.
+- Unix socket / named pipe server implementation.
+- `scorel attach` command.
+- Process discovery files, PID files, or daemon state files.
+- Remote WebSocket transport.
+- Token persistence or token refresh commands.
+
+## Acceptance Criteria
+
+- `DaemonTransport` remains the only transport interface consumed by `DaemonClient`.
+- Root `@scorel/client` export remains browser-safe and has no Node API imports.
+- A Node socket transport entrypoint is reserved for local daemon work, without leaking into browser-safe imports.
+- `connect`, `subscribe_events`, `resync_events`, `get_status`, and `disconnect` have protocol-level tests covering request/response shape and event delivery expectations.
+- Per-session `lastSeq` behavior is tested at the daemon/client boundary.
+- Existing embedded daemon/client CLI tests still pass.
+
+## Tests
+
+- `pnpm --filter @scorel/protocol test`
+- `pnpm --filter @scorel/client test`
+- `pnpm --filter @scorel/daemon test`
+- `pnpm typecheck && pnpm test`
+
+## Affected Paths
+
+- `packages/protocol/src/transport.ts`
+- `packages/protocol/src/wire.ts`
+- `packages/client/src/`
+- `packages/daemon/src/`
+- `docs/spec/client.md`
+- `docs/spec/daemon.md`
+- `docs/ROADMAP.md`
+
+## Risks And Boundaries
+
+- If the socket contract is overfit to Unix sockets, Windows named pipe support will be harder later. Keep the protocol interface transport-neutral.
+- If Node-only code leaks through `@scorel/client`, WebUI support will be compromised. Protect this with package boundary tests.
+- Do not add remote auth or WebSocket behavior here; M3 is local daemon only.