---
id: 02-core-runner-protocol
epic: walking-skeleton
title: core-runner-protocol package — versioned, zod-validated message schemas
type: technical-story
status: todo
feature: core-runner-protocol
depends-on: []
blocks: [04-runner-app-protocol-clone-install, 09-editor-package]
created: 2026-07-12T10:24:14Z
---

## Goal

Ship `@repo/core-runner-protocol`: versioned, zod-validated message schemas for the runner protocol (hello/ready, clone, install, scan, adapter-start, render-frame, status/error events) shared by features, editor, and runner, so the three sides cannot drift apart silently (PRD user story 7).

## Why

The runner protocol is plain WS/JSON, not tRPC (ADR-027) — which means nothing type-checks the wire unless every message is zod-parsed against one shared schema package. Every other story in this epic (runner app, provisioner, lifecycle events, editor frame) consumes these schemas; they must exist first.

## Done when

- `@repo/core-runner-protocol` exists as a green optional core package.
- Message envelope carries `protocolVersion: "0"` and a workspace-scoped auth token (PRD Implementation decisions).
- Zod-validated schemas exist for: hello/ready, clone, install, scan, adapter-start, render-frame, and status/error events — status events carry stage + elapsed (ui-gap §5 staged-progress), error events carry named causes.
- Unit tests cover accept/reject round-trips for every message type (`.strict()` schemas reject unknown fields).
- `pnpm typecheck && pnpm lint && pnpm test && pnpm conformance && pnpm fallow:audit && pnpm coverage:diff` all pass after each task.

## In scope

- `pnpm turbo gen core-package runner-protocol` scaffold.
- Versioned envelope + the message schema set listed above.
- Schema unit tests.

## Out of scope

- The WS server/client implementations (stories 04 and 07) — this package is schemas only.
- Protocol version negotiation beyond the pinned `"0"` (later PRDs).
- Watch/HMR messages (`discovery-and-library`).

## Tasks

- [ ] Run `pnpm turbo gen core-package runner-protocol` → green `@repo/core-runner-protocol` package shell.
- [ ] Add the versioned protocol surface: message envelope (`protocolVersion: "0"`, workspace-scoped auth token) + zod-validated `.strict()` schemas for hello/ready, clone, install, scan, adapter-start, render-frame, and status/error events (staged progress carries stage + elapsed; errors carry named causes), with unit tests covering accept/reject round-trips for every message type.
