@chanlerdev/scorel 0.0.6 → 0.0.8

package/docs/CHANGELOG.md

@@ -2,6 +2,59 @@
 
 ## Unreleased
 
+## 0.0.8 - 2026-06-26
+
+### Highlights
+
+- New `scorel run` command for headless, non-interactive task execution
+- GUI now correctly loads memory status for the selected project on session preload
+- Sessions can be attached even when provider credentials are missing
+
+### Changes
+
+- Added `scorel run` command with multiple prompt sources, execution options, provider overrides, and machine-readable summary output
+- GUI now fetches and displays memory status for the selected project during app initialization
+- Provider settings UI no longer autosaves on credential mode change, preventing incomplete data saves
+- Daemon session loading no longer requires a runtime; sessions can be attached without provider API keys configured
+
+### Fixes
+
+- Fixed GUI not loading memory status for the selected project on session preload
+- Fixed provider attach failure when provider config is incomplete (e.g., missing API key)
+
+### Verification
+
+- Tests cover `scorel run` prompt sources, output formats, summary, timeout exit code, and provider overrides
+- Unit test confirms memory status is fetched for correct project on app mount
+- Tests verify sessions can be loaded and messages sent even when provider credentials are missing
+
+## 0.0.7 - 2026-06-24
+
+### Highlights
+
+- Introduce structured system_reminder content blocks across CLI, GUI, WebUI, and daemon, replacing ad-hoc XML strings.
+- Bundle GUI runtime dependencies for self-contained execution.
+
+### Changes
+
+- System reminders now use structured `system_reminder` content blocks with origin, visibility, and scope, enabling consistent handling across all interfaces.
+- GUI's CLI runtime is now bundled with all dependencies, eliminating the need for node_modules.
+
+### Fixes
+
+- Snip tool result no longer exposes internal span IDs or event counts to the model, keeping output concise.
+
+### Breaking Changes
+
+- Protocol version incremented from 4 to 5; session headers must now carry version 5.
+
+### Verification
+
+- All existing tests pass, with new tests covering system_reminder lowering, message-attached reminders, projector filtering, and bundled runtime integrity.
+
+- Protocol version incremented to 5 with structured `system_reminder` content blocks.
+- Snip tool results now return a concise model-visible confirmation while keeping internal span details out of provider context.
+
 ## 0.0.6 - 2026-06-23
 
 ### Highlights

package/docs/ROADMAP.md

@@ -601,8 +601,8 @@ M5 WebUI 的正式产品方向记录在 [`S0030`](spec/ship/S0030-webui-product-
 | 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 |
+| M9.F1.28 | [`S0107`](spec/ship/S0107-system-reminder-unification.md) | 统一 system reminder 的持久化、构造、LLM 投影和 UI visibility 语义 | Done |
+| M9.F1.29 | [`S0108`](spec/ship/S0108-gui-bundled-cli-runtime.md) | GUI release 内置同版本 CLI runtime，packaged GUI 用 bundle 内可执行文件启动本地 Host | Done |
 
 **Not in M9 Follow-up**:
 
@@ -783,8 +783,9 @@ HTTP adapter 必须映射已有 Host use cases，不复制领域逻辑。
 | [`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 |
+| [`S0107`](spec/ship/S0107-system-reminder-unification.md) | System reminder unification | Done |
+| [`S0108`](spec/ship/S0108-gui-bundled-cli-runtime.md) | GUI bundled CLI runtime | Done |
+| [`S0109`](spec/ship/S0109-scorel-run-headless-task-runner.md) | `scorel run` headless task runner | Active |
 
 ---
 

package/docs/spec/channels.md

@@ -94,7 +94,7 @@ running default  -> follow_up queue
 
 ## 6. Source Reminder
 
-每个 IM turn 会在用户消息前注入 hidden channel reminder：
+每个 IM turn 会在用户消息前注入 hidden `harness_item kind="channel_context"`。`buildContext()` 会把它转成 `system_reminder` block，provider adapter 最后 lower 成类似下面的模型输入文本：
 
 ```xml
 <system-reminder>

package/docs/spec/events.md

@@ -340,7 +340,7 @@ interface EventTypeHandler<T extends PersistentEvent> {
 ```typescript
 type LlmAction =
   | { action: "include"; message: ScorelMessage }       // 正常包含为一条消息
-  | { action: "merge_prev"; content: string }           // 合入前一条消息（<system-reminder> 包裹）
+  | { action: "merge_prev"; reminder: SystemReminderContentBlock } // 合入前一条 tool_result
   | { action: "skip" }                                  // 不包含在 LLM context 中
   | { action: "barrier"; summary: ScorelMessage }       // 替换上方所有消息，注入 summary，停止遍历
 ```
@@ -350,7 +350,7 @@ type LlmAction =
 | Event 类型 | convertToLlm | convertToDisplay |
 |---|---|---|
 | `message`（user/assistant/tool_result） | `include` — 原样包含 | 正常气泡 |
-| `message`（meta.source = "steer"） | `merge_prev` — 合入前一条 tool_result 的 `<system-reminder>`；无 tool_result 则 `include` 作为独立 user msg | 内联小字提示 |
+| `harness_item`（steer / runtime guidance） | `merge_prev` — 合入前一条 tool_result 的 `system_reminder` block；无 tool_result 则作为独立 user msg | 内联小字提示 |
 | `message`（meta.source = "followUp"） | 同 steer | 内联 "追加任务" 标记 |
 | `rewind` | `skip` | "回退到此处" 标记 |
 | `branch` | `skip` | "切换分支" 标记 |
@@ -397,23 +397,40 @@ function buildContext(tree: SessionTree, leafId: EventId): ScorelMessage[] {
 
 ---
 
-## 7. `<system-reminder>` 通用 Harness 注入机制
+## 7. `system_reminder` 通用 Harness 注入机制
 
 ### 7.1 用途
 
-`<system-reminder>` 是 Scorel harness 向 LLM 传递旁路信息的统一格式。所有非用户直接输入、但需要 LLM 看到的系统级内容都用此标签包裹。
+`system_reminder` 是 Scorel harness 向 LLM 传递旁路信息的结构化 content block。所有非用户直接输入、但需要 LLM 看到的系统级内容都先表达成结构化 block；`<system-reminder>` 只是 provider adapter 最后生成的传输 envelope。
 
 ### 7.2 使用场景
 
 | 场景 | 注入内容 | 注入位置 |
 |------|---------|---------|
 | Steer（用户中途插话） | 用户的引导文字 | merge 进前一条 tool_result |
-| Hook 上下文（UserPromptSubmit 等） | hook 产出 | user message / tool_result 末尾 |
+| User message sidecar | 当前 turn 时间、用户输入引用、`snip.userMessageId` | 同一条 user message 的 `content` |
+| Hook 上下文（UserPromptSubmit 等） | hook 产出 | user message / tool_result |
 | Memory 召回 | 记忆内容 | tool_result 末尾 |
 | 系统提醒（超时、配额等） | 通知文本 | tool_result 末尾 |
 | Channel 来源标注 | 来自哪个群/频道 | user message 内 |
 
-### 7.3 格式
+### 7.3 Canonical 格式
+
+```typescript
+interface SystemReminderContentBlock {
+  type: "system_reminder";
+  kind: SystemReminderKind;
+  origin: "system" | "user" | "tool" | "skill";
+  text: string;
+  visibility: "model" | "display" | "compact";
+  scope: "message" | "turn" | "next_model_call" | "session";
+  data?: Record<string, unknown>;
+}
+```
+
+### 7.4 Provider lowering
+
+Provider adapter 把 canonical block lower 成当前模型输入格式。默认 text envelope 是：
 
 ```xml
 <system-reminder>
@@ -421,12 +438,13 @@ function buildContext(tree: SessionTree, leafId: EventId): ScorelMessage[] {
 </system-reminder>
 ```
 
-### 7.4 注入规则
+### 7.5 注入规则
 
-- **工具循环中**：merge 进最近一条 tool_result 的 content 末尾
-- **无 tool_result 时（idle / turn 结束后）**：作为独立 user message（或附加到 user message 内）
+- **跟随 user message**：作为同一条 `user_message.content` 的 sidecar block，创建时固定，保持 prompt-cache 稳定。
+- **工具循环中**：merge 进最近一条 tool_result 的 content 末尾；provider 不支持时 fallback 为紧邻 tool result batch 的 user message。
+- **无 tool_result 时（idle / turn 结束后）**：作为独立 user message。
 
-### 7.5 LLM System Prompt 声明
+### 7.6 LLM System Prompt 声明
 
 LLM 在 system prompt 中被告知：
 

package/docs/spec/runtime.md

@@ -174,15 +174,15 @@ Steer message persist 为**独立 PersistentEvent**（role = "user"，`meta.sour
 
 | 前面有 tool_result | 行为 |
 |---|---|
-| ✅ 有 | `merge_prev` — 合入前一条 tool_result content 末尾，用 `<system-reminder>` 包裹 |
+| ✅ 有 | `merge_prev` — 合入前一条 tool_result content 末尾，内容为结构化 `system_reminder` block |
 | ❌ 没有（idle 状态） | `include` — 作为独立 user message |
 
-LLM 最终看到的（工具循环中）：
+Provider lowering 后 LLM 最终看到的（工具循环中）：
 ```
 tool_result: "文件内容...\n\n<system-reminder>\n别改了，直接跑测试\n</system-reminder>"
 ```
 
-LLM 最终看到的（idle 时）：
+Provider lowering 后 LLM 最终看到的（idle 时）：
 ```
 user: "别改了，直接跑测试"
 ```

package/docs/spec/session.md

@@ -198,8 +198,8 @@ function buildContext(tree: SessionTree, leafId: EventId): ScorelMessage[] {
         messages.unshift(result.message);
         break;
       case "merge_prev":
-        // 合入 messages 中最后一条 tool_result 的 content 末尾（<system-reminder> 包裹）
-        mergeIntoPrevToolResult(messages, result.content);
+        // 合入 messages 中最后一条 tool_result 的 content 末尾（system_reminder block）
+        mergeIntoPrevToolResult(messages, result.reminder);
         break;
       case "skip":
         break;
@@ -216,7 +216,7 @@ function buildContext(tree: SessionTree, leafId: EventId): ScorelMessage[] {
 
 各事件类型的 LlmAction：
 - `message`（普通）→ `include`
-- `message`（meta.source = "steer"/"followUp"）→ `merge_prev`（前面有 tool_result 时）或 `include`（没有时）
+- `harness_item` / runtime guidance → `merge_prev`（前面有 tool_result 时）或独立 user message，内容为结构化 `system_reminder` block
 - `compact` → `barrier`（注入 summary，停止遍历）
 - `rewind` / `branch` / `channel_inject` / `session_info` / `custom` → `skip`
 - `custom_message` → `include`
@@ -367,7 +367,7 @@ if (estimateTokens(compactCandidates) > threshold) {
 - `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>`）
+- `harness_item` / runtime guidance → `merge_prev` 或独立 user message，内容为结构化 `system_reminder` block
 
 换言之，应用层能玩的花样很多，LLM 始终只看到 handler 声明要暴露的内容。
 

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

@@ -56,7 +56,7 @@ Expose a lazily available `Snip` runtime tool that lets the agent request hiding
 { "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 Host validates the request, resolves the model-visible short alias to a target span, appends a `context_control` event, and returns a brief model-visible confirmation. Internal span details such as `anchorUserEventId`, `throughEventId`, and hidden event count may remain in structured tool result details for diagnostics, but provider context must only receive the concise confirmation. 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()`.
 

package/docs/spec/ship/S0107-system-reminder-unification.md

@@ -2,98 +2,154 @@
 
 ## Goal
 
-Unify how Scorel represents, persists, projects, and displays system reminders.
+Unify Scorel's runtime reminders as structured, model-facing context fragments.
 
-The business value is prompt and transcript hygiene: runtime guidance should reach the model through one stable contract, without ad-hoc `<system-reminder>` string construction scattered across daemon, session replay, tool-result merge paths, or future context-control features. UI should consistently hide or display reminder evidence based on explicit visibility, not by parsing model-facing text.
+The business value is prompt and transcript hygiene on a high-frequency path. Scorel will routinely attach reminders to user messages, inject reminders while a turn is running, and route reminders through different provider message formats. This must be one stable product contract, not ad-hoc `<system-reminder>` strings scattered across daemon, session replay, tool-result merge paths, UI projectors, or provider adapters.
 
 ## Scope
 
-### Reminder Source Model
+### Structured Reminder Block
+
+Add a protocol-level content block:
+
+```typescript
+type SystemReminderKind =
+  | "attachment"
+  | "time"
+  | "message_ref"
+  | "skill_listing"
+  | "skill_delta"
+  | "memory"
+  | "channel_context"
+  | "steer"
+  | "todo_nudge"
+  | "runtime_notice"
+  | "compact_summary";
+
+type SystemReminderOrigin = "system" | "user" | "tool" | "skill";
+
+type SystemReminderScope =
+  | "message"          // travels with one persisted message whenever that message is in context
+  | "turn"             // relevant to the user turn that created it
+  | "next_model_call"  // runtime nudge, consumed by the next provider call
+  | "session";         // durable session context such as initial memory
+
+type SystemReminderVisibility = "model" | "display" | "compact";
+
+interface SystemReminderContentBlock {
+  type: "system_reminder";
+  kind: SystemReminderKind;
+  origin: SystemReminderOrigin;
+  text: string;
+  visibility: SystemReminderVisibility;
+  scope: SystemReminderScope;
+  data?: Record<string, unknown>;
+}
+```
 
-Define one internal reminder representation for model-facing non-user guidance.
+`<system-reminder>` remains the model-facing transport envelope, but it is no longer stored or hand-written by feature code. Callers create structured reminder blocks; core/provider projection renders the envelope.
 
-Current sources include:
+### Two Placement Modes
 
-- `harness_item` events such as memory, channel context, skill listing, skill delta, and steer.
-- Compact summary messages.
-- Model-only metadata attached to a specific `user_message`, such as `snip.userMessageId`.
-- Future runtime guidance that should be visible to the model but not necessarily displayed as transcript text.
+System reminders can appear in two product situations:
 
-The new contract must preserve the existing product distinction:
+1. **Message-attached reminders**: created together with a `user_message` and persisted in that message's `content`.
+   - Examples: current time for the submitted turn, `snip.userMessageId`, references to prior user messages, channel context that explains the submitted text.
+   - These are stable sidecars. They are created when the message is persisted, so replaying the same message later does not mutate historical content or break prompt-cache prefix stability.
 
-- Some reminders are standalone session events (`harness_item`).
-- Some reminders are attached to a specific message to preserve prompt-cache prefix stability.
-- Some reminders can merge into a previous `tool_result`.
+2. **Runtime injected reminders**: appended while a turn is running or between provider calls.
+   - Examples: steer, skill delta, a nudge that the model has not used `TodoWrite`, runtime notices.
+   - These remain standalone `harness_item` events because they are independent session facts. `buildContext()` lowers them into structured reminder blocks and then places them according to provider-safe rules.
 
-### Single Renderer
+### Canonical Context And Provider Lowering
 
-Move `<system-reminder>` wrapping behind a single public core helper or equivalent abstraction. Callers should provide reminder content and placement intent, not hand-write:
+Scorel keeps a provider-neutral context:
 
-```text
-<system-reminder>
-...
-</system-reminder>
-```
+- `ScorelMessage.content` may contain `system_reminder` blocks.
+- UI/display projectors use block type and `visibility`; they must not parse `<system-reminder>` text.
+- Provider adapters receive canonical `ScorelMessage[]` and lower `system_reminder` blocks to the provider's legal representation.
 
-The renderer must keep the existing prompt contract:
+Default lowering keeps the current prompt contract:
 
-```text
+```xml
 <system-reminder>
 content
 </system-reminder>
 ```
 
-Any future format change must happen in one place.
+Provider placement rules:
+
+- User-message sidecars are rendered inside the same user message after visible user text.
+- Runtime reminders prefer merge-after-tool-result when a valid previous tool result exists.
+- If a provider cannot legally merge after a tool result, fallback to a standalone user message immediately after the tool result batch.
+- Provider-level system/developer prompt is not used for runtime reminders.
 
-### Visibility And Projection
+### Core Helper Surface
 
-Clarify and consolidate visibility semantics:
+Core owns reminder construction and rendering:
 
-- `harness_item.visibility` controls whether the harness event is displayed as transcript evidence.
-- Message-level model-only blocks are included in LLM context but hidden from WebUI and GUI transcript projection.
-- Display projectors must not parse `<system-reminder>` text to decide visibility.
-- Provider adapters should receive already-rendered model-facing text or a normalized reminder block from core, not duplicate reminder formatting.
+- `createSystemReminderBlock(input)`
+- `renderSystemReminder(block | text)`
+- `renderSystemReminderText(text)`
+- `appendSystemReminderToToolResult(message, block)`
+- `systemReminderMessage(block, meta?)`
 
-### Prompt Cache Stability
+Feature code must pass semantic fields: `kind`, `origin`, `scope`, `visibility`, `text`, optional `data`. Feature code must not write `<system-reminder>` tags.
 
-Reminder placement must not rewrite older model context on later turns.
+### Existing Source Migration
 
-For reminders attached to a specific persisted message, the model-facing block must be created when that message is persisted. Later `buildContext()` calls may clone or filter it, but must not mutate historical messages based on later session state.
+Migrate these sources to structured reminder blocks:
+
+- `snip.userMessageId` model-only block attached to every persisted user message.
+- `harness_item` conversion for memory, channel context, skill listing, skill delta, steer, runtime notice, and future todo nudges.
+- compact summary injection.
+- GUI and WebUI transcript projection for model-only blocks.
+
+`harness_item` remains the persistent event for standalone runtime/session injections. S0107 does not need a new event type unless the implementation proves `harness_item` cannot carry the contract.
 
 ## Not In Scope
 
-- Changing snip semantics from S0106.
-- Replacing `harness_item` with a new event type unless the implementation proves the existing event cannot express the contract.
-- Changing provider-level system prompt assembly.
-- UI controls for browsing hidden reminders.
+- Changing `snip` behavior from S0106.
+- Adding UI controls for browsing hidden reminders.
 - Backfilling or migrating old session JSONL files.
 - Renaming `<system-reminder>` in the model-facing prompt.
+- Moving runtime reminders into provider-level system/developer prompts.
+- Replacing all event-type conversion with a full handler registry.
 
 ## Acceptance Criteria
 
+- Protocol supports `system_reminder` content blocks.
 - No daemon or feature code hand-writes `<system-reminder>` strings.
-- `buildContext()` uses the shared reminder renderer for `harness_item` and compact summaries.
-- Snip's model-only user-message id block uses the shared reminder renderer or normalized reminder block.
-- WebUI and GUI hide model-only message blocks without parsing reminder text.
+- `buildContext()` uses shared core helpers for `harness_item` and compact summary conversion.
+- `snip.userMessageId` is a message-attached `system_reminder` block with stable prompt-cache behavior across later turns.
+- Provider adapters lower `system_reminder` blocks through the shared renderer, including reminders inside user messages and merged tool results.
+- WebUI and GUI hide model-only reminder blocks without parsing reminder text.
 - Existing harness visibility behavior stays intact:
-  - hidden harness items do not render as visible turns;
-  - display harness items still render as lightweight transcript evidence.
-- Prompt-cache stability is preserved for message-attached reminders: replaying the same persisted user message in later provider calls produces the same content.
-- Provider adapters do not own system-reminder formatting rules.
+  - hidden harness items do not render as visible transcript turns;
+  - display/compact harness items can still render as lightweight transcript evidence.
 - `pnpm typecheck && pnpm test` passes.
 
 ## Testing Requirements
 
-- Core session tests for the shared reminder renderer and `buildContext()` conversion.
+- Protocol tests for `system_reminder` content block round trip / exhaustiveness.
+- Core session tests for:
+  - message-attached reminder blocks rendering to `<system-reminder>` in provider context;
+  - `harness_item` conversion producing structured reminder blocks;
+  - merge-after-tool-result behavior preserving tool result content;
+  - compact summary using the shared reminder renderer.
 - Daemon embedded test proving snip's message-attached reminder remains stable across later turns.
-- WebUI and GUI projector tests proving model-only blocks are hidden while display harness items remain visible.
-- Regression test or static check that common runtime paths no longer hand-write `<system-reminder>` literals outside the shared renderer and tests/docs.
+- Provider adapter test proving `system_reminder` blocks are lowered to `<system-reminder>` text.
+- WebUI and GUI projector tests proving model-only reminder blocks are hidden while display harness items remain visible.
+- Static regression check that common runtime paths no longer hand-write `<system-reminder>` literals outside tests/docs and the shared renderer.
 
 ## Impacted Files
 
+- `packages/protocol/src/messages.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` or a new core reminder module
+- `packages/core/src/provider/pi-ai.ts`
+- `packages/core/src/provider/pi-ai.test.ts`
 - `packages/daemon/src/index.ts`
 - `packages/daemon/src/embedded/embedded.test.ts`
 - `apps/webui/lib/events/projector.ts`
@@ -106,7 +162,12 @@ For reminders attached to a specific persisted message, the model-facing block m
 
 ## Risks And Boundaries
 
-- Reminder placement affects prompt-cache behavior. A cleanup that moves snip ids from persisted user messages into later dynamic `buildContext()` injection would regress S0106.
-- Tool-result merge behavior is easy to break. The implementation must preserve valid assistant tool-call / tool-result replay.
-- UI should use explicit visibility metadata, not text parsing. Parsing `<system-reminder>` in UI would make display behavior depend on prompt formatting.
-- A broader content-block redesign may be attractive, but S0107 should stay focused on unifying reminder construction and projection.
+- Reminder placement affects prompt-cache behavior. Do not move message-attached reminders into dynamic `buildContext()` injection.
+- Tool-result merge behavior must preserve valid assistant tool-call / tool-result replay.
+- Runtime reminders can be frequent. The data model must keep origin, kind, scope, and visibility explicit so future skill, time, todo, IM, and provider-specific rules do not become string parsing.
+- UI must use explicit metadata, not text parsing.
+- A full event handler registry remains a later refactor; S0107 should ship the stable reminder contract first.
+
+## Status
+
+Done.

package/docs/spec/ship/S0108-gui-bundled-cli-runtime.md

@@ -105,4 +105,4 @@ pnpm release patch --dry-run
 
 ## Status
 
-Active.
+Done.

package/docs/spec/ship/S0109-scorel-run-headless-task-runner.md

@@ -0,0 +1,172 @@
+# S0109: Scorel Run Headless Task Runner
+
+## Goal
+
+Add a non-interactive `scorel run` command for one-shot agent tasks, matching the headless shape of tools such as `claude -p` and `codex exec`.
+
+The command must run through Scorel's existing embedded Host, daemon/client, runtime, tool, project registry, and JSONL session path. It must be usable by external harnesses such as Harbor / Terminal-Bench without entering the interactive `scorel chat` REPL.
+
+## Scope
+
+- Add `scorel run [prompt]`.
+- Add prompt input forms:
+  - positional prompt
+  - `--prompt <text>`
+  - `--prompt-file <path>`
+  - `--stdin`
+- Add execution options:
+  - `--cwd <dir>`
+  - `--state-dir <dir>`
+  - `--sessions-dir <dir>`
+  - `--session <id>`
+  - `--timeout-ms <ms>`
+  - `--output-format text|json|stream-json|none`
+  - `--summary <path>`
+  - `--quiet`
+  - `--model <role-or-id>`
+  - `--provider <name>`
+  - `--api <openai-completions|openai-responses|google-generative-ai|anthropic-messages>` / `--protocol <...>`
+  - `--base-url <url>` / `--baseurl <url>`
+  - `--api-key <key>` / `--apikey <key>`
+- Reuse the same product path as `scorel chat`: embedded `ScorelHost`, `DaemonClient`, project registration, real runtime, and append-only session JSONL.
+- Return only after the submitted user turn finishes, errors, or times out.
+- Write an optional summary JSON containing status, session id, project id, cwd, state/sessions paths, session JSONL path, elapsed time, output format, and error details.
+
+## Product Boundary
+
+This spec targets the minimum complete command contract needed for Terminal-Bench / Harbor installed-agent integration. The command must be stable enough for an external harness to:
+
+1. provide one task instruction;
+2. run Scorel in a specific task workspace;
+3. isolate state and session artifacts per trial;
+4. pin provider protocol, base URL, API key, and model from the harness;
+5. wait for one agent turn to finish or time out;
+6. read deterministic summary/session artifacts without parsing human-oriented stdout.
+
+This is intentionally narrower than the full non-interactive command surface exposed by mature coding agents such as Claude Code `-p` or Codex `exec`.
+
+Current required parity:
+
+- one-shot prompt execution;
+- workspace selection;
+- model/provider selection;
+- output format selection;
+- timeout;
+- stable exit codes;
+- session artifact persistence;
+- machine-readable summary file.
+
+Known gaps versus Claude Code / Codex that are not required for this first Terminal-Bench integration:
+
+- explicit permission modes and tool allow/deny lists;
+- sandbox / approval policy flags;
+- system prompt and append-system-prompt overrides;
+- structured input protocol beyond plain prompt/stdin;
+- budget and cost limits;
+- MCP config injection;
+- debug file / verbose diagnostic switches;
+- partial-message streaming controls;
+- tool-set selection;
+- no-persistence mode;
+- full resume/continue UX beyond explicit `--session` load-or-create behavior.
+
+These gaps should be prioritized from real Terminal-Bench failure evidence, not copied wholesale from other CLIs.
+
+## Command Contract
+
+Examples:
+
+```bash
+scorel run "Fix the failing test and run the relevant verification command."
+scorel run --prompt "Summarize this project" --output-format json
+scorel run --prompt-file /tmp/instruction.txt --cwd /workspace --state-dir /tmp/scorel-state --summary /logs/agent/scorel-summary.json --output-format none
+scorel run --prompt-file /tmp/instruction.txt --api openai-completions --base-url https://api.example.test/v1 --api-key "$API_KEY" --model gpt-5.4-mini
+cat instruction.txt | scorel run --stdin --output-format stream-json
+```
+
+Prompt precedence is strict:
+
+1. positional prompt
+2. `--prompt`
+3. `--prompt-file`
+4. `--stdin`
+
+Exactly one prompt source is allowed.
+
+Exit codes:
+
+- `0`: run completed.
+- `1`: runtime / provider / agent error.
+- `2`: command usage or configuration error.
+- `124`: timeout.
+
+Output formats:
+
+- `text`: stream assistant text deltas and tool summaries, like a compact non-interactive `scorel chat`.
+- `json`: print one final JSON object.
+- `stream-json`: print newline-delimited JSON events for live deltas and final status.
+- `none`: print no stdout except unexpected lower-level output; intended for benchmark harnesses that use files and container state.
+
+## Not In Scope
+
+- Harbor agent adapter.
+- Terminal-Bench dataset or leaderboard submission.
+- ATIF trajectory export.
+- Background Bash / long-running command lifecycle.
+- Permission sandbox policy.
+- Resuming previous headless runs beyond explicit `--session` load-or-create behavior.
+- Replacing `scorel chat`.
+
+## Acceptance Criteria
+
+- `scorel run --prompt ...` creates or resumes a session and submits exactly one user message.
+- `scorel run --base-url ... --api-key ... --api ... --model ...` uses a run-local provider config without writing Scorel config files.
+- The command exits after `DaemonClient.sendMessage()` resolves.
+- `--cwd` controls the registered project workdir and runtime tool cwd.
+- `--state-dir` isolates project registry and Scorel home.
+- `--sessions-dir` controls where `{sessionId}.jsonl` is written.
+- `--summary` writes deterministic JSON on success, runtime error, and timeout.
+- `--output-format none` produces no normal stdout on success.
+- `--output-format json` produces parseable final JSON.
+- `--output-format stream-json` emits parseable JSONL progress/final events.
+- Timeout returns exit code `124` and best-effort cancels the active session.
+- Usage errors return exit code `2` and print a concise error.
+
+## Testing
+
+- Extend `apps/cli/src/index.test.ts`.
+- Add focused tests for:
+  - prompt via `--prompt`.
+  - prompt file.
+  - stdin prompt.
+  - output format `none`.
+  - output format `json`.
+  - summary file content and session JSONL path.
+  - prompt source conflict.
+  - timeout exit code and summary.
+
+Run:
+
+```bash
+pnpm --filter @scorel/app-cli test -- index
+pnpm --filter @scorel/app-cli typecheck
+```
+
+Before completion, run the repository check:
+
+```bash
+pnpm typecheck && pnpm test
+```
+
+## Affected Paths
+
+- `apps/cli/src/index.ts`
+- `apps/cli/src/index.test.ts`
+- `docs/ROADMAP.md`
+- `docs/spec/ship/S0109-scorel-run-headless-task-runner.md`
+
+## Risks
+
+- Treating `scorel run` as a wrapper around REPL stdin would make completion unreliable. It must call the daemon/client request path directly.
+- Parsing stdout in external harnesses would be fragile. Summary JSON and session JSONL are the durable artifacts.
+- `--state-dir` and `--sessions-dir` must remain explicit to support one-task-per-container benchmark isolation.

package/package.json

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