@chanlerdev/scorel 0.0.4 → 0.0.6

package/docs/CHANGELOG.md

@@ -2,6 +2,79 @@
 
 ## Unreleased
 
+## 0.0.6 - 2026-06-23
+
+### Highlights
+
+- Packed GUI now bundles its own CLI runtime, enabling fully self-contained local Host startup without Node.js or global CLI.
+- Agents can now use the `snip` tool to hide completed user turns from future context — reducing token waste and keeping conversations focused.
+
+### Changes
+
+- GUI now bundles its own CLI runtime for fully self-contained Host startup (no Node.js or global CLI required).
+- Added `snip` tool that agents can call to mark a completed user turn as hidden from future LLM context.
+- Protocol version incremented to 4 with new `context_control` event and `hide_user_turn` operation.
+- UI (GUI and WebUI) now hides model-only text blocks (like `snip` reminders) from the visible transcript.
+- Provider adapters now pass each tool's own parameter schema instead of hardcoding tool-specific parameters.
+
+### Fixes
+
+- Increased Host startup timeout from 10s to 30s to prevent timeouts in slower development environments.
+
+### Breaking Changes
+
+- Protocol version incremented from 3 to 4; requires protocol-version-aware clients.
+- Packaged GUI no longer accepts `SCOREL_CLI_ENTRYPOINT` or `SCOREL_NODE_PATH` environment variables.
+
+### Verification
+
+- Unit and release tests verify bundled CLI usage in packaged GUI, snip tool end-to-end behavior, hidden spans in context builds, protocol version bump, and UI projector rendering.
+
+### Internal
+
+- Added planned spec S0107 for system reminder unification (documentation only).
+
+## 0.0.5 - 2026-06-19
+
+### Highlights
+
+- New CLI commands `scorel version`, `scorel update`, and `scorel upgrade` for software lifecycle management.
+- Oversized Bash tool output is now archived to session artifacts, returning compact head/tail projections to the model.
+- GUI auto-update support with macOS DMG/ZIP packaging and incremental updates.
+
+### Changes
+
+- GUI and daemon now honor the selected chat model when sending messages.
+- GUI settings are more resilient: ignore stale device responses, error boundaries on settings sections, and fixed state reset when switching devices.
+- `scorel host serve` and `scorel host start` no longer idle-timeout by default; only convenience daemons (GUI auto-start, `scorel up`) enforce a 15-minute idle timeout.
+- GUI auto-start uses an ephemeral port to avoid conflicts with user-started daemons.
+
+### Fixes
+
+- GUI provider model selection now persists correctly across profile refreshes and session creation.
+- Daemon lifecycle hardened: foreground daemon stays alive until Ctrl+C/SIGTERM.
+
+### Verification
+
+- Unit tests for update helpers (semver comparison, npm check/install, auto-update gate).
+- Unit tests for GUI main process (electron-updater import, manual update item, tray setup).
+- Integration test for release asset collection and version lockstep.
+- Tests for oversized Bash archive and projection logic.
+- Tests for daemon idle timeout behavior.
+- Tests for GUI settings resilience (stale data, error boundary, state reset).
+- Tests for model selection fallback and normalization.
+
+### Internal
+
+- Update SHIP.md to clarify that small bug fixes may skip spec requirement; only changes affecting stable contracts or user-visible direction need a spec.
+- Oversized Bash results are written to session-scoped artifacts, excluded from diagnostics and Relay.
+
+- Add `scorel version`, `scorel update`, and `scorel upgrade`.
+- Add hourly Host auto-update checks gated by active work state.
+- Add GUI macOS release packaging and Electron updater metadata to the release path.
+- Add GUI application menu and macOS status bar menu entries for manual update checks and common app actions.
+- Document unsigned macOS GUI quarantine bypass command.
+
 ## 0.0.4 - 2026-06-14
 
 ### Highlights

package/docs/ROADMAP.md

@@ -598,6 +598,11 @@ M5 WebUI 的正式产品方向记录在 [`S0030`](spec/ship/S0030-webui-product-
 | M9.F1.22 | [`S0100`](spec/ship/S0100-gui-provider-danger-zone.md) | GUI Provider 删除按钮位置初版 | Done |
 | M9.F1.23 | [`S0101`](spec/ship/S0101-gui-device-settings-polish.md) | GUI Settings 改为设备级配置，修正 Provider 删除位置、Token 文案、设备展开/重命名交互 | Done |
 | M9.F1.24 | [`S0102`](spec/ship/S0102-device-only-config.md) | Config 彻底收敛为设备级唯一配置，移除 Project config 运行时语义 | Done |
+| M9.F1.25 | [`S0103`](spec/ship/S0103-daemon-lifecycle-and-settings-resilience.md) | Daemon 生命周期按入口区分，并修复 GUI Settings remote 切换黑屏风险 | Done |
+| M9.F1.26 | [`S0105`](spec/ship/S0105-cli-update-and-gui-release.md) | CLI 命令面统一补齐、NPM 手动/自动更新、GUI release 打包和增量更新框架 | Done |
+| M9.F1.27 | [`S0106`](spec/ship/S0106-snip-context-control.md) | `context_control` 持久事件和 `snip` tool，让 agent 隐藏已完成 user turn 的未来 LLM context 投影 | Done |
+| M9.F1.28 | [`S0107`](spec/ship/S0107-system-reminder-unification.md) | 统一 system reminder 的持久化、构造、LLM 投影和 UI visibility 语义 | Planned |
+| M9.F1.29 | [`S0108`](spec/ship/S0108-gui-bundled-cli-runtime.md) | GUI release 内置同版本 CLI runtime，packaged GUI 用 bundle 内可执行文件启动本地 Host | Active |
 
 **Not in M9 Follow-up**:
 
@@ -774,6 +779,12 @@ HTTP adapter 必须映射已有 Host use cases，不复制领域逻辑。
 | [`S0100`](spec/ship/S0100-gui-provider-danger-zone.md) | GUI Provider danger-zone placement | Done |
 | [`S0101`](spec/ship/S0101-gui-device-settings-polish.md) | GUI device-scoped Settings polish | Done |
 | [`S0102`](spec/ship/S0102-device-only-config.md) | Device-only config | Done |
+| [`S0103`](spec/ship/S0103-daemon-lifecycle-and-settings-resilience.md) | Daemon lifecycle and Settings resilience | Done |
+| [`S0104`](spec/ship/S0104-tool-result-artifacts.md) | Tool result artifacts for oversized Bash output | Done |
+| [`S0105`](spec/ship/S0105-cli-update-and-gui-release.md) | CLI update and GUI release | Done |
+| [`S0106`](spec/ship/S0106-snip-context-control.md) | Snip context control | Done |
+| [`S0107`](spec/ship/S0107-system-reminder-unification.md) | System reminder unification | Planned |
+| [`S0108`](spec/ship/S0108-gui-bundled-cli-runtime.md) | GUI bundled CLI runtime | Active |
 
 ---
 

package/docs/SHIP.md

@@ -25,6 +25,8 @@
 ```bash
 pnpm install
 pnpm scorel       # 在当前目录进入交互式项目会话
+pnpm scorel --version
+pnpm scorel update
 ```
 
 Hosted WebUI 路径：
@@ -35,7 +37,7 @@ open https://scorel.chanler.dev
 pnpm scorel pair <pair-code>
 ```
 
-`scorel host serve` 会以前台调试模式启动本机 Host、注册当前目录为初始 Project，并默认连接官方 Relay。`scorel host start` 会启动或复用后台 singleton Host，并返回到 shell；`scorel host stop` 显式关闭它。`scorel up` / `pnpm dev` 只作为本地开发便利入口：确保后台 Host 可用，然后启动本地 WebUI，但不拥有 Host 生命周期。后台 Host 无 client、无 active work、无 active IM 时会按 idle timeout 自动退出；active IM 会保持 Host 存活。
+`scorel host serve` 会以前台调试模式启动本机 Host、注册当前目录为初始 Project，并默认连接官方 Relay；前台 Host 默认一直存活，直到 Ctrl+C / SIGTERM，除非显式传入 `--idle-timeout-ms`。`scorel host start` 会启动或复用后台 singleton Host，并返回到 shell；直接后台启动的 CLI Host 默认一直存活，直到 `scorel host stop` 或进程退出。`scorel up` / `pnpm dev` 只作为本地开发便利入口：确保后台 Host 可用，然后启动本地 WebUI，但不拥有 Host 生命周期。GUI / CUI 自动拉起的后台 Host 无 client、无 active work、无 active IM 时会按 15 分钟 idle timeout 自动退出；active IM 会保持 Host 存活。
 
 ---
 
@@ -102,7 +104,7 @@ docs/spec/ship/S####-slug.md
 - 影响文件 / 包
 - 风险与边界
 
-没有 S spec，不开始实现。Bug fix 也需要 S spec，可以很短。
+没有 S spec，不开始实现。局部 bug fix 可以不创建 S spec；如果修复会改变稳定契约、配置/协议/数据边界或用户可见产品方向，就先补 S spec。
 
 ### 3. Ship
 
@@ -140,7 +142,7 @@ S####: <type>: <description>
 
 规则：
 
-- 一个 PR 对应一个 S spec。
+- 一个 PR 对应一个 S spec；局部 bug fix 可以不对应 S spec。
 - Commit message 使用 title-only semantic commit：只写标题，不写正文。
 - 按业务含义拆 commit，不把无关实现混在一起。
 - 文档、实现、测试可以拆 commit，但 PR title 必须带 S 编号。
@@ -205,9 +207,12 @@ pnpm release patch --no-generate-notes
 - 检查 working tree
 - 执行 check
 - 执行 WebUI production build
+- 执行 GUI production build
 - 构建 public `scorel` npm package
+- 将同版本 public `scorel` CLI runtime vendored 进 GUI app bundle，供 packaged GUI 用 bundle 内绝对路径启动本机 Host
 - 执行 `npm pack` 安装烟雾测试
 - bump 所有 package version
+- 构建 GUI macOS dmg / zip release assets，并生成 `latest-mac.yml` 与 blockmap 增量更新 metadata
 - 默认用 DeepSeek V4 Flash 从上一个 `v*` tag 之后的 commits 生成 changelog notes
 - 更新 changelog；只有显式 `--no-generate-notes` 时才写入最小版本标题
 - commit `release: vX.Y.Z`
@@ -215,11 +220,11 @@ pnpm release patch --no-generate-notes
 - publish root `scorel` package to npm
 - push branch + tag
 - create GitHub Release from the same generated changelog notes
-- upload the same-version `npm pack` tarball as the only GitHub Release asset
+- upload the same-version `npm pack` tarball and GUI macOS release assets to the GitHub Release
 
 Release notes 使用 `DEEPSEEK_API_KEY` 调用 DeepSeek 官方 API，默认 endpoint 为 `https://api.deepseek.com/v1`，默认模型为 `deepseek-v4-flash`。Dry-run 在缺少 key 或 API 失败时可打印 deterministic fallback preview；正式 release 默认要求 AI notes 成功，除非显式传入 `--no-generate-notes`。
 
-GitHub Actions 提供手动触发入口，默认执行 `patch` dry-run。正式 release 使用 `GITHUB_TOKEN` 创建 GitHub Release；正式 publish 需要仓库 secret `NPM_TOKEN`，对应 npm 账号当前为 `chanlerdev`。AI release notes 需要仓库 secret `DEEPSEEK_API_KEY`。
+GitHub Actions 提供手动触发入口，默认执行 `patch` dry-run。正式 release 使用 `GITHUB_TOKEN` 创建 GitHub Release；正式 publish 需要仓库 secret `NPM_TOKEN`，对应 npm 账号当前为 `chanlerdev`。AI release notes 需要仓库 secret `DEEPSEEK_API_KEY`。GUI macOS 产物当前以 unsigned build 发布，workflow 设置 `CSC_IDENTITY_AUTO_DISCOVERY=false`；有 Apple Developer 账号后再补 signing/notarization。
 
 ---
 

package/docs/spec/events.md

@@ -143,7 +143,22 @@ interface CompactEvent extends PersistentEventBase {
 
 构建 context 时：从 leaf 往 root 走，遇到 CompactEvent → 注入 summary，停止继续向上。旧事件仍在 JSONL 中（可查阅），但不进入 LLM context。
 
-### 4.5 `channel_inject` — 外部来源元数据
+### 4.5 `context_control` — 控制上下文投影
+
+```typescript
+interface ContextControlEvent extends PersistentEventBase {
+  type: "context_control";
+  operation: "hide_user_turn";
+  anchorUserEventId: EventId;
+  throughEventId: EventId;
+  actor: "agent" | "user" | "system";
+  reason?: string;
+}
+```
+
+`hide_user_turn` 隐藏一个已完成 user turn span：从 `anchorUserEventId` 开始，到同一路径下一条 `user_message` 前一条事件结束。它只影响未来 `buildContext()` 的 LLM 输入投影；原始 JSONL 事件仍保留并可用于 UI、审计和 resync。
+
+### 4.6 `channel_inject` — 外部来源元数据
 
 ```typescript
 interface ChannelInjectEvent extends PersistentEventBase {
@@ -340,6 +355,7 @@ type LlmAction =
 | `rewind` | `skip` | "回退到此处" 标记 |
 | `branch` | `skip` | "切换分支" 标记 |
 | `compact` | `barrier` — 注入 summary，停止向上遍历 | "已压缩" 折叠块 |
+| `context_control` | `filter` — 从未来 LLM context 中排除指定 user turn span | "已 snip" 标记 |
 | `channel_inject` | `skip` | 来源 badge "from Telegram" |
 | `session_info` | `skip` | "模型切换为 X" 通知 |
 | `custom` | `skip` | Extension 自定义 |

package/docs/spec/session.md

@@ -345,6 +345,17 @@ if (estimateTokens(compactCandidates) > threshold) {
 - 在 compact 点之前分叉的其他分支不受影响
 - 旧事件仍在 JSONL 中，可供历史浏览
 
+### 6.3 Snip Context Control
+
+`snip` 不删除 JSONL。它 append `context_control operation="hide_user_turn"`，让后续 `buildContext()` 在 active path 上过滤一个已完成 user turn span。
+
+安全边界：
+
+- 目标必须是当前 active path 上的 `user_message`。
+- 目标之后必须存在下一条 `user_message`，因此不能 snip 当前正在执行的 turn。
+- 隐藏范围是目标 `user_message` 到下一条 `user_message` 前一条事件，保证 tool_call / tool_result 成对隐藏，不留下孤儿工具结果。
+- 原始事件仍保留在 JSONL 中，UI 和审计可以继续查看。
+
 ---
 
 ## 7. 两层消息在本模块的落点
@@ -355,6 +366,7 @@ if (estimateTokens(compactCandidates) > threshold) {
 - buildContext 通用遍历时调用每个 event 的 handler，不 hardcode 任何类型
 - `rewind` / `branch` / `channel_inject` / `session_info` / `custom` → `skip`（不进入 LLM）
 - `compact` → `barrier`（注入 summary，停止向上）
+- `context_control` → `filter`（从未来 LLM context 排除指定 user turn span）
 - `message`（meta.source = "steer"）→ `merge_prev`（合入前一条 tool_result 的 `<system-reminder>`）
 
 换言之，应用层能玩的花样很多，LLM 始终只看到 handler 声明要暴露的内容。

package/docs/spec/ship/S0064-gui-product-intent-and-boundary.md

@@ -29,7 +29,7 @@ Lock M9 GUI as a Project-first desktop app before implementation. The GUI should
 
 - Do not scaffold Electron in S0064.
 - Do not implement GUI screens.
-- Do not add SSH, direct WS + token, OAuth, account systems, or GUI auto-update.
+- Do not add SSH, direct WS + token, OAuth, account systems, or GUI auto-update in S0064. GUI auto-update is introduced later by S0105 as release infrastructure.
 - Do not publish or package desktop installers.
 - Do not change the public npm CLI package surface.
 

package/docs/spec/ship/S0073-provider-model-profile-contract.md

@@ -76,10 +76,17 @@ Host runtime must use the selected model for each session/turn:
   available model or role;
 - CLI can continue using the default role without exposing a new command flag in this
   spec;
-- GUI composer can choose an available model for new prompts/sessions;
+- GUI composer can choose an available model for the next main chat prompt, including
+  prompts sent into an existing session;
+- background model tasks such as session title generation, session memory, foreground
+  compact, and memory dream use the configured `auxiliary` role unless a later spec
+  defines a more specific routing contract;
 - session metadata records the selected model id and role when known;
 - session header persists enough selected-model metadata to keep resume auditable if
   config later changes;
+- if a restored session references a selected model that no longer exists in the
+  current device config, Host falls back through the persisted role or current
+  `standard` role instead of failing attach/resume;
 - assistant events keep recording actual provider/model metadata from pi-ai.
 
 Tool creation must use the actual selected model's context window, not a global model

package/docs/spec/ship/S0103-daemon-lifecycle-and-settings-resilience.md

@@ -0,0 +1,61 @@
+# S0103: Daemon Lifecycle And Settings Resilience
+
+## Goal
+
+Clarify daemon lifetime by entrypoint and make GUI Settings resilient when switching devices and sections, especially after selecting a Relay device.
+
+Business value: a VPS demo host should stay online when the user explicitly starts it, while GUI/CUI convenience daemons still clean themselves up after local use. Settings failures must surface as recoverable errors, not a black renderer.
+
+## Scope
+
+- `scorel host start` launches a background host that stays alive until explicit stop, process signal, crash, or machine shutdown.
+- `scorel host serve` is foreground: it stays alive until Ctrl+C / SIGTERM unless the user explicitly provides `--idle-timeout-ms`.
+- GUI auto-start and `scorel up` auto-start keep the existing 15 minute idle shutdown policy.
+- GUI auto-start binds an ephemeral local port so a user-owned daemon on the default port cannot make GUI startup fail.
+- `--idle-timeout-ms 0` remains the explicit "no idle shutdown" value.
+- GUI Settings must ignore stale settings responses from a previously selected device.
+- GUI Settings must render a local error fallback instead of blacking out the whole app when a Settings section throws.
+- CDP verification covers Settings remote-device switching without renderer errors.
+
+## Not In Scope
+
+- Changing active IM keepalive semantics. Active IM still prevents idle shutdown.
+- Adding a new public `--keep-alive` flag; this spec keeps the existing `--idle-timeout-ms 0` primitive and fixes defaults.
+- Remote SSH device installation or management.
+
+## Acceptance Criteria
+
+- Direct `scorel host start` spawns `host serve` with idle shutdown disabled by default.
+- Direct `scorel host serve` does not idle-exit by default; Ctrl+C/SIGTERM still stops it.
+- `scorel up` spawns the daemon with a 15 minute idle timeout.
+- GUI auto-start spawns the daemon with a 15 minute idle timeout.
+- GUI auto-start uses the persisted `daemon.json` actual port instead of assuming the default daemon port is free.
+- Settings device changes reset device-scoped settings state and ignore stale async responses.
+- Settings section render errors show an in-app fallback and do not remove the app shell.
+- CDP GUI verification seeds a device config, switches to a remote device in Settings, flips across Settings sections, and fails on renderer errors.
+
+## Tests
+
+- CLI daemon tests cover background start idle disable, foreground serve default no-idle, explicit idle timeout, and active IM keepalive.
+- `scorel up` tests assert the internal daemon spawn passes the 15 minute idle timeout.
+- GUI renderer tests cover stale local settings data not overwriting remote settings data.
+- CDP GUI verification covers remote Settings section switching and device-level config persistence.
+
+## Files
+
+- `apps/cli/src/daemon-cli.ts`
+- `apps/cli/src/up-cli.ts`
+- `apps/gui/src/main.ts`
+- `apps/gui/src/renderer/App.tsx`
+- `apps/gui/src/renderer/settings/SettingsShell.tsx`
+- `apps/gui/src/renderer/settings/sections/ModelSection.tsx`
+- `apps/gui/src/renderer/settings/sections/ProviderSection.tsx`
+- `scripts/verify-m9-gui-cdp-e2e.ts`
+- `docs/SHIP.md`
+- `docs/ROADMAP.md`
+- `docs/CHANGELOG.md`
+
+## Risks
+
+- A foreground host without idle shutdown can run forever. That is intended because terminal ownership and Ctrl+C are visible to the user.
+- GUI/CUI auto-start must remain explicit about its 15 minute idle timeout; otherwise changing host defaults would make local helper daemons permanent.

package/docs/spec/ship/S0104-tool-result-artifacts.md

@@ -0,0 +1,64 @@
+# S0104: Tool Result Artifacts
+
+## Goal
+
+Keep long tool results useful without letting them dominate model context.
+
+When a tool result is too large, Scorel should preserve the full result as a session-owned artifact and put only a compact, actionable projection in the model-facing tool result.
+
+## Scope
+
+- Add a session-owned artifact path for oversized tool results:
+
+```text
+~/.scorel/sessions/{sessionId}.artifacts/{toolCallId}/result.txt
+```
+
+- Start with `Bash` stdout/stderr because it is the highest-risk long-output source.
+- Preserve the full command result in `result.txt`, including exit code, cwd, stdout, and stderr.
+- Return a compact tool result containing:
+  - exit code;
+  - cwd;
+  - full artifact path;
+  - complete result byte count;
+  - stdout/stderr byte counts;
+  - a budgeted head/tail projection of the oversized streams.
+- Treat `maxOutputBytes` as the total projection snippet budget across stdout/stderr, not as a per-stream head/tail allowance. For example, a 16,000-byte projection budget should not turn into 16,000 bytes of stdout head plus 16,000 bytes of stdout tail plus the same again for stderr.
+- Keep session JSONL append-only. Do not rewrite or delete old tool result events.
+- Keep diagnostics free of full prompt text and full tool results.
+- Keep Relay and attach-cache out of this storage path.
+
+## Not In Scope
+
+- Background Bash, task id, poll, stop, or monitor semantics.
+- Artifact retention policy, compression, upload, or remote retrieval.
+- Rewriting existing session JSONL files.
+- Applying artifact projection to `Read`, `Grep`, `Glob`, or MCP tools.
+- Provider-specific token accounting.
+
+## Acceptance Criteria
+
+- `Bash` output at or below the existing output limit behaves as before.
+- `Bash` output above the limit writes the complete result to `result.txt`.
+- Oversized `Bash` model-facing content includes the artifact path, `resultBytes`, and budgeted head/tail snippets instead of only the leading bytes.
+- The artifact file contains the complete stdout/stderr text, not only the projected snippets.
+- The tool result details expose artifact metadata for UI/diagnostics without requiring it to enter rebuilt model context.
+- Existing `buildContext()` behavior still strips tool execution details from replayed model context.
+- `pnpm --filter @scorel/core test -- src/tools/coding-tools.test.ts`
+- `pnpm --filter @scorel/daemon test -- src/embedded/embedded.test.ts`
+- `pnpm typecheck && pnpm test`
+
+## Impacted Files
+
+- `packages/core/src/tools/coding-tools.ts`
+- `packages/core/src/tools/coding-tools.test.ts`
+- `packages/core/src/session/index.ts`
+- `packages/daemon/src/index.ts`
+- CLI / GUI runtime creation paths that call `createRealRuntime`
+- `docs/ROADMAP.md`
+
+## Risks And Boundaries
+
+- Full command output can contain secrets. The artifact path is local session data and must not be copied into diagnostics, attach-cache, or Relay.
+- Head/tail snippets can still expose sensitive text. This is no worse than the current truncated result, but future permission policy should handle sensitive commands explicitly.
+- Artifact paths are local to the daemon-owning machine. Remote clients can see the path as evidence, but remote file retrieval is a separate future protocol.

package/docs/spec/ship/S0105-cli-update-and-gui-release.md

@@ -0,0 +1,128 @@
+# S0105: CLI Update And GUI Release
+
+## Goal
+
+Make Scorel's user-facing command surface complete enough for release users, and make CLI / GUI updates part of the same release story.
+
+## Scope
+
+- Add top-level `scorel version` / `scorel --version`.
+- Add manual `scorel update` and `scorel upgrade` commands for the public npm package.
+- Add Host-side automatic npm update checks:
+  - check npm latest once per hour
+  - install only when no active work is running, or active work has been stale for at least three hours
+  - after a successful background update, stop the Host with an `auto-update` reason so the next entry start uses the new binary
+- Keep `scorel` as the default interactive project command, and keep lifecycle/diagnostic commands grouped under product nouns: `host`, `pair`, `relay`, `webui`, `up`, `project`, `logs`.
+- Add GUI release packaging to the same GitHub Release:
+  - Electron macOS dmg + zip targets
+  - `latest-mac.yml`
+  - `.blockmap` metadata for incremental updates
+  - `electron-updater` bootstrap in packaged GUI builds
+- Add normal desktop update affordances:
+  - application menu `Check for Updates...`
+  - macOS status bar menu with show, settings, check updates, Host status, and quit
+- Document unsigned macOS build handling for users without an Apple Developer account.
+
+## Non-Goals
+
+- Do not add auth/account commands before Scorel has a real account system.
+- Do not add deprecated aliases for old command shapes.
+- Do not publish GUI through npm.
+- Do not claim notarization or Gatekeeper trust without Apple Developer signing credentials.
+- Do not make Relay or hosted WebUI own update state.
+
+## Contract
+
+### CLI Surface
+
+The stable user command groups are:
+
+```text
+scorel [--session <id>] [--cwd <dir>]
+scorel chat [--session <id>] [--cwd <dir>]
+scorel attach --session <id> --remote <ws-url> --token <token>
+scorel host start|serve|status|stop|reset
+scorel pair <pair-code>
+scorel relay serve
+scorel webui
+scorel up
+scorel project list|add|remove
+scorel logs
+scorel version
+scorel update
+scorel upgrade
+```
+
+This mirrors the broad shape used by mature agent CLIs: one default interactive command, explicit session/control commands, and a direct update command.
+
+### CLI Update
+
+`scorel update` and `scorel upgrade` both:
+
+- query `npm view @chanlerdev/scorel version`
+- compare against the installed package version with semver ordering
+- run `npm install -g @chanlerdev/scorel@<latest>` only when latest is newer
+- print a clear no-op message when already current
+
+Host auto-update uses the same updater helper. The active-work gate is generic: it reads Host runtime/queue activity, not filenames, paths, screenshots, or one failure sample.
+
+### GUI Release
+
+`apps/gui` remains private and separate from the npm CLI package. Release packaging uses Electron Builder with GitHub provider metadata so `electron-updater` can check the same GitHub Release.
+
+The release asset set is:
+
+```text
+<npm pack tarball>
+apps/gui/release/latest-mac.yml
+apps/gui/release/*.dmg
+apps/gui/release/*.dmg.blockmap
+apps/gui/release/*.zip
+apps/gui/release/*.zip.blockmap
+```
+
+The macOS Action runs with `CSC_IDENTITY_AUTO_DISCOVERY=false` until signing/notarization credentials exist.
+
+## Acceptance Criteria
+
+- `scorel --help` lists update/version commands.
+- `scorel --version` and `scorel version` print the installed version.
+- `scorel update` / `scorel upgrade` have tested npm check/install behavior.
+- Host auto-update gate is covered by tests.
+- GUI packaged app initializes `electron-updater` only when packaged.
+- GUI exposes manual update checks from both the application menu and the macOS status bar menu.
+- GUI registers a macOS status bar menu with Host status and common app actions.
+- Release script version lockstep includes `apps/gui/package.json`.
+- Release script uploads GUI installer/update metadata assets to GitHub Release.
+- README documents manual update, automatic update, GUI packaging, and unsigned macOS `xattr` workaround.
+
+## Test Requirements
+
+```bash
+pnpm --filter @scorel/app-cli test -- update-cli.test.ts
+pnpm --filter @scorel/app-gui test -- main-menu.test.ts
+node --test scripts/release-gui.test.mjs
+pnpm typecheck
+pnpm test
+git diff --check
+```
+
+## Affected Paths
+
+- `apps/cli/src/index.ts`
+- `apps/cli/src/update-cli.ts`
+- `apps/cli/src/daemon-cli.ts`
+- `packages/daemon/src/index.ts`
+- `apps/gui/package.json`
+- `apps/gui/src/main.ts`
+- `scripts/release.mjs`
+- `.github/workflows/release.yml`
+- `README.md`
+- `docs/SHIP.md`
+- `docs/ROADMAP.md`
+
+## Risks
+
+- `npm install -g` can fail on machines where the user lacks permission for the global prefix. The command reports the npm error instead of silently mutating local state.
+- Auto-updating a running Host cannot replace the current Node process in-place. The short-stop mechanism exits after successful installation; GUI/WebUI/CLI entrypoints can then start the new binary.
+- Unsigned macOS apps are viable for local distribution but not trustworthy public distribution. Notarization should be added once an Apple Developer account is available.

package/docs/spec/ship/S0106-snip-context-control.md

@@ -0,0 +1,113 @@
+# S0106: Snip Context Control
+
+## Goal
+
+Let long-running sessions remove a completed user turn from future model context without deleting the underlying session record.
+
+The business value is context hygiene: when an earlier user turn led the agent down a noisy or obsolete path, the user or agent can mark that whole turn as no longer relevant so future model calls stop paying attention to it. The original JSONL remains the evidence chain for UI, audit, resync, and debugging.
+
+## Scope
+
+### Stable User Turn References
+
+Every persisted `user_message` already has a durable `EventId`. S0106 treats that event id as the source of truth for snip targeting. The model-facing id is a stable short alias derived from the real `EventId`; the alias resolves back to the real event id but is not a storage key.
+
+When the Host creates a `user_message`, it appends a model-only text block to that same persisted message:
+
+```text
+<system-reminder>
+snip.userMessageId: u_...
+</system-reminder>
+```
+
+The block is persisted with the message so future `buildContext()` replays do not rewrite earlier user messages and do not invalidate prompt-cache prefixes. UI projectors hide model-only text blocks from the visible transcript.
+
+### Context Control Event
+
+Add a persistent control event:
+
+```ts
+type ContextControlEvent = {
+  type: "context_control";
+  operation: "hide_user_turn";
+  anchorUserEventId: EventId;
+  throughEventId: EventId;
+  actor: "agent" | "user" | "system";
+  reason?: string;
+};
+```
+
+The event is append-only and does not participate in the conversation tree. `buildContext()` folds these events as control state and filters the active path before producing LLM messages.
+
+`hide_user_turn` semantics:
+
+- `anchorUserEventId` must identify a `user_message` on the active session path.
+- The hidden span starts at that user event.
+- The hidden span ends at the event before the next `user_message` on the same path, or the active leaf when there is no later user message.
+- The resolved end is stored as `throughEventId`.
+- The span is hidden from future `buildContext()` calls after the control event is appended.
+- Original events stay in JSONL and continue to be visible through session replay and UI projection.
+
+### `snip` Tool
+
+Expose a lazily available `Snip` runtime tool that lets the agent request hiding a completed user turn from future context. The tool accepts:
+
+```json
+{ "userMessageId": "u_...", "reason": "optional short reason" }
+```
+
+The Host validates the request, resolves the model-visible short alias to a target span, appends a `context_control` event, and returns a tool result describing what changed. The tool result is still part of the current turn; the hidden span disappears on the next context build.
+
+The tool is session-context control, not a generic coding tool. It must be registered by the Host with access to the current lane, not by `createCodingTools()`.
+
+Tool parameter schemas are owned by `AgentTool` definitions. Provider adapters must pass through the tool's declared schema instead of hard-coding behavior for specific tool names such as `snip`.
+
+## Not In Scope
+
+- Physically deleting, truncating, or rewriting historical JSONL.
+- Arbitrary single-message deletion.
+- Snipping across branches.
+- User-facing GUI controls for browsing snipped spans.
+- A CLI slash command.
+- Automatic snip heuristics.
+- Reusing `compact` for snip. Compact summarizes old context; snip excludes a specific user turn.
+
+## Acceptance Criteria
+
+- `PersistentEvent` includes `context_control`.
+- Session replay folds `hide_user_turn` events into control state.
+- `buildContext()` excludes the hidden user-turn span from future LLM context.
+- The excluded span can include assistant tool calls and tool results without leaving orphan tool results in context.
+- JSONL remains append-only; original user/assistant/tool events remain loadable after snip.
+- Repeated snip of the same target is idempotent enough to keep context stable.
+- Invalid targets fail as tool errors and do not append control events.
+- `snip` is registered by the Host and can append `context_control` from a real runtime tool call path.
+- The model can discover snippable user turn ids from its normal context projection; tests must not rely on out-of-band `send_message` response data.
+- User turn ids are persisted at user-message creation time, so replaying the same turn in later provider calls does not change that message and preserves prompt-cache stability.
+- Model-only short id blocks are hidden from WebUI and GUI transcript projection.
+- The `snip` `AgentTool` schema exposes `userMessageId` and optional `reason`, and provider adapters preserve tool-owned schemas without name-specific branches.
+- Full validation passes with `pnpm typecheck && pnpm test`.
+
+## Testing Requirements
+
+- Core session tests for context-control parsing, replay, and context filtering.
+- Protocol tests for exhaustive event handling.
+- Daemon embedded test proving `snip` appends `context_control` and the next provider call no longer receives the hidden turn.
+
+## Impacted Files
+
+- `packages/protocol/src/events.ts`
+- `packages/protocol/src/index.test.ts`
+- `packages/core/src/session/index.ts`
+- `packages/core/src/session/session.test.ts`
+- `packages/core/src/tools/index.ts`
+- `packages/daemon/src/index.ts`
+- `packages/daemon/src/embedded/embedded.test.ts`
+- `docs/ROADMAP.md`
+- `README.md`
+
+## Risks And Boundaries
+
+- Hiding the wrong turn is worse than compacting too much. Target resolution must use real `EventId`s and reject non-user targets.
+- Tool-call/tool-result pairing can be broken by arbitrary deletion. This spec only hides full user-turn spans.
+- Snip is context projection, not evidence deletion. UI and session replay must still show the original events unless a later explicit product decision adds a separate display filter.