---
id: 04-runner-app-protocol-clone-install
epic: walking-skeleton
title: runner app — protocol server, clone stage, install stage
type: technical-story
status: todo
feature: runner
depends-on: [01-vite-kitchen-fixture, 02-core-runner-protocol]
blocks: [05-runner-scan-and-preview-adapter, 06-runner-provisioner-port]
created: 2026-07-12T10:24:14Z
---

## Goal

Ship the first half of `apps/runner`: a WS server speaking `@repo/core-runner-protocol` (hello/ready handshake gated on the workspace-scoped auth token), then the clone stage (PAT via ephemeral credential helper, spec §6 verbatim) and the install stage (package-manager detection), each emitting staged progress and named error events, each proven by the protocol integration suite against a real spawned runner and a `git daemon`-served `vite-kitchen`.

## Why

The runner ↔ repo-toolchain seam is one of the three risks this epic exists to burn down. Clone and install are where credentials touch disk and subprocesses — the credential-leak assertions (no PAT in URLs, argv, logs, or `.git/config`; spec §15) must grow up with the code, not after it. App-tier imperative code is expected here (PRD Implementation decisions); the protocol is the contract, so tests assert through the protocol and never against runner internals (PRD Testing decisions).

## Done when

- `apps/runner` exists; every inbound/outbound message is zod-parsed against `core-runner-protocol`; handshake rejects a bad/missing workspace-scoped token.
- Clone stage delivers the PAT to git via an ephemeral credential helper (spec §6 mechanics verbatim); credential never appears in any log, process argv, or `.git/config` in the runner workspace — asserted by the integration suite.
- Install stage detects the package manager and installs, streaming staged progress events.
- Named error events for bad URL, bad token, and install failure (PRD user story 5).
- Protocol integration suite (real spawned runner + `git daemon`-served fixture, real WS) passes in CI on ubuntu.
- `pnpm typecheck && pnpm lint && pnpm test && pnpm conformance && pnpm fallow:audit && pnpm coverage:diff` all pass after each task.

## In scope

- `apps/runner` app scaffold (app-tier — no feature generator applies; template app conventions).
- WS server + envelope parsing + hello/ready handshake + status/error emission.
- Clone stage with ephemeral credential helper + leak assertions.
- Install stage with package-manager detection + progress events.
- Integration tests using `core-testing`'s git-serving helpers (story 01).

## Out of scope

- Scan + preview adapter + agent script (story 05).
- Provisioning of the runner (story 06) — tests spawn it directly.
- Watch/HMR, perf budgets (`discovery-and-library`); Next.js adapter (`preview-and-nextjs-depth`).
- Local runner / CLI agent (`local-runner-cli`).

## Tasks

- [ ] Scaffold `apps/runner`: WS server speaking `@repo/core-runner-protocol` (every message zod-parsed), hello/ready handshake gated on the workspace-scoped auth token, status/error event emission; integration test spawns the real runner and completes the handshake over real WS.
- [ ] Add the clone stage: git clone of the requested repo with the PAT delivered via an ephemeral credential helper (spec §6 verbatim — never in URLs, argv, logs, or `.git/config`), staged progress events; integration test clones the `git daemon`-served `vite-kitchen`, asserts credential-leak absence (grep argv/logs/`.git/config`), and asserts named failure events for bad URL / bad token.
- [ ] Add the install stage: package-manager detection + install with staged progress events; integration test asserts install completes on the fixture and a named failure event is emitted on install error.