Winterrks · Oct 25, 2026 · Oct 25, 2026 · Oct 25, 2026
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -6,7 +6,7 @@ Guidance for Claude Code (claude.ai/code) when working in this repository. This
 
 Winter is a macOS-native AI assistant: a TypeScript/Bun daemon (`winter-core`) plus a native Swift menu-bar app. They speak JSON-RPC 2.0 over NDJSON on a Unix socket (`<WINTER_HOME>/run/core.sock`; default home `~/.winter`). The daemon is the single source of truth; every client — CLI, Mac app, phone — is a view over its event stream.
 
-**The daemon runs no agent loop of its own.** Every session is a runtime child driven through the router (`@yanlinglabs/winter-runtime-sdk`) on the Winter agent runtime — the only leg; every model runs on it, Claude included. Code sessions spawn the `winter` binary; chat and dispatch run it EMBEDDED in `winter-core`, one Bun Worker per session. Session modes are `code`, `dispatch`, `chat`. **Cowork is not an implemented session mode** — the protocol names it (`SESSION_MODES`) but `session.create` refuses it for every role (`unsupported_topology`) and no runtime-facing type can hold it; see [docs/cowork-status.md](docs/cowork-status.md). The daemon owns everything around the child: IPC, event-sourced session storage, settings, approvals, the capability tools it hands the child over MCP, the hooks, and the SDK-message→`SessionEvent` projector.
+**The daemon runs no agent loop of its own.** Every session is a runtime child driven through the router (`@yanlinglabs/winter-runtime-sdk`) on the Winter agent runtime — the only leg; every model runs on it, Claude included. Code sessions spawn the `winter` binary; chat and dispatch run it EMBEDDED in `winter-core`, one Bun Worker per session. Session modes are `code`, `dispatch`, `chat`. **Cowork is not an implemented session mode** — the protocol names it (`SESSION_MODES`) but `session.create` refuses it for every role (`unsupported_topology`) and no runtime-facing type can hold it; its native VM/guest source is inert and has never booted; see [docs/cowork-status.md](docs/cowork-status.md). The daemon owns everything around the child: IPC, event-sourced session storage, settings, approvals, the capability tools it hands the child over MCP, the hooks, and the SDK-message→`SessionEvent` projector.
 
 ## Commands
 
@@ -57,7 +57,7 @@ Plain links, not `@` imports — read the file whose area you are about to touch
 | [providers-and-credentials.md](docs/claude/providers-and-credentials.md) | Before touching a Keychain slot, `credential.*`/`provider.*` doors, the host-credential broker, the boot Keychain passes or Anthropic/Console sign-in. |
 | [internal-jobs.md](docs/claude/internal-jobs.md) | Before touching titles, the bash safety reviewer, the dreamer or the session cleaner — model/effort/credential resolution and the role problems. |
 | [protocol-and-remote.md](docs/claude/protocol-and-remote.md) | Before changing a `SessionEvent` variant or field (the 7-step checklist), adding an RPC method, or touching what a remote/phone client sees (allowlists, history, transients, thinking pill, phone mirror). |
-| [settings-and-migrations.md](docs/claude/settings-and-migrations.md) | Before adding a setting (live reload, the one-reader rule) or touching the legacy `~/.norma` home or project migration. |
+| [settings-and-migrations.md](docs/claude/settings-and-migrations.md) | Before adding a setting (live reload, the one-reader rule), touching the legacy `~/.norma` home or project migration, or bumping the runtime-state schema (currently v21). |
 | [runtime-home.md](docs/claude/runtime-home.md) | Before touching `<home>/sdk`, run folders, MCP/settings scopes and trust, Migration C, saved answers or the plugin format. |
 | [tool-surface.md](docs/claude/tool-surface.md) | Before changing what a model can call: capability servers and plain names, deferral, chat/dispatch allowed lists, web tools, hooks, read/write fences, sandbox escapes, saved allow rules, skills. |
 | [dispatch-and-messaging.md](docs/claude/dispatch-and-messaging.md) | Before touching mid-turn pushes (the fold), turn pairing, `SpawnSession`/children, `SendMessage`/`ListAgents`/`TaskStop`, `ListSessions`, or the Dispatch pill's command mode and terminal. |
@@ -69,8 +69,8 @@ Plain links, not `@` imports — read the file whose area you are about to touch
 | [headless.md](docs/claude/headless.md) | Before touching the `headless` backend, the Winter Headless helper, its local-network rules or the Chromium embed layout. |
 | [usage.md](docs/claude/usage.md) | Before touching usage and cost tracking: `packages/core/src/usage/`, the projector's `onTurnUsage`, `usage.*`, `settings.usage`, reading the user's Codex/Claude Code/Antigravity/OpenCode usage or plans, `apple/Winter/Sources/Usage/`. |
 | [testing.md](docs/claude/testing.md) | Before running or writing tests, a verify gate, the live computer-use suite, or anything reading daemon logs/temp dirs. |
-| [release.md](docs/claude/release.md) | Before bumping a version, writing release notes or cutting a release. |
-| [cowork.md](docs/claude/cowork.md) | Before touching `packages/core/src/cowork/**`, `packages/protocol/src/cowork.ts`, `apple/Cowork/**`, host-storage-fence or home-fence cowork roots, `refreshForStorage`, or the `workspace.*` / `project.*` methods and events. |
+| [release.md](docs/claude/release.md) | Before bumping a version, writing release notes or cutting a release — including the Cowork native-pair choice (`COWORK_NATIVE=omit` or both libkrun inputs) and a schema bump's rollback line. |
+| [cowork.md](docs/claude/cowork.md) | Before touching `packages/core/src/cowork/**`, `packages/protocol/src/cowork.ts`, `apple/Cowork/**`, `scripts/cowork-guest-artifact/**`, host-storage-fence or home-fence cowork roots, `refreshForStorage`, or the `workspace.*` / `project.*` methods and events. |
 
 Other references: `winter-vs-cc-tools.md` (repo root, the live tool comparison with Claude Code), `apple/ComputerUse/PROTOCOL.md` (the helper's wire contract), `apple/ComputerUse/WinterBrowserHost/PROTOCOL.md` (Winter for Chrome's).
 

diff --git a/docs/RELEASE-NOTES-cowork-schema-v18.md b/docs/RELEASE-NOTES-cowork-schema-v18.md
diff --git a/docs/RELEASE-NOTES-cowork-schema.md b/docs/RELEASE-NOTES-cowork-schema.md
@@ -0,0 +1,9 @@
+# Runtime-state schema v21 (Cowork tables) - release note draft
+
+The version numbers below are pinned against `RUNTIME_STATE_SCHEMA_VERSION` (`packages/core/src/runtime-state/db.ts`); change them with it (main's `test/cowork/schema-docs-pin.test.ts` holds them once this branch lands).
+
+Draft line for the release that first carries the Cowork integration (Cowork itself stays off):
+
+> Winter's local database (`runtimes/runtime-state.db`) moves to schema v21 on first launch. Going back to an older Winter afterwards needs one step first: quit Winter, run `winter migrate --cowork-schema --rollback` with this version's command-line tool, then install the older app. Skipping the step makes the older Winter refuse to open your sessions until the database is rolled back.
+
+Facts for the writer: the rollback accepts v8 to v21 and drops only empty Cowork tables (it refuses with `cowork-data-present` if one has a row, which no production build can write); nothing else in the database changes. The step is needed for every store at v8 or higher, so an intermediate integration build (v18, v19 or v20) needs it too. See `docs/claude/settings-and-migrations.md` (Runtime-state schema v21 and the way back) for what v18 to v21 each add.