@chanlerdev/scorel 0.0.4 → 0.0.5

package/docs/CHANGELOG.md

@@ -2,6 +2,47 @@
 
 ## Unreleased
 
+## 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,8 @@ 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 |
 
 **Not in M9 Follow-up**:
 
@@ -774,6 +776,9 @@ 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 |
 
 ---
 

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,11 @@ pnpm release patch --no-generate-notes
 - 检查 working tree
 - 执行 check
 - 执行 WebUI production build
+- 执行 GUI production build
 - 构建 public `scorel` npm package
 - 执行 `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 +219,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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chanlerdev/scorel",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "description": "Replayable, recoverable, remotely controllable AI Agent workspace.",
   "type": "module",
   "packageManager": "pnpm@11.1.2",