agentic-dev/docs/work/epics/walking-skeleton/04-runner-app-protocol-clone-install/_story.md

id, epic, title, type, status, feature, depends-on, blocks, created, updated

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

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.

Landed: b090e26 + 750ab44 + ec7bf94 (cherry-picks), two independent adversarial reviews approved — credential-leak surface airtight (blank-then-veect helper, PAT via child env only, proven by unit builder + integration grep of logs/.git/config/.git surface + spawn-suite whole-child-output grep). Auth proven via a Basic-auth dumb-HTTP git fixture (real 401→helper→retry, asserts exact x-access-token:PAT). 98 tests, 96.6% coverage. Honest boundary: real smart-HTTP/GitHub deferred to later PRDs (documented in apps/runner/AGENTS.md).