---
id: 07-runner-lifecycle-events-and-realtime
epic: walking-skeleton
title: runner lifecycle — status events, scan event, realtime channel
type: technical-story
status: todo
feature: workspaces
depends-on:
  [
    03-workspaces-feature-core,
    05-runner-scan-and-preview-adapter,
    06-runner-provisioner-port,
  ]
blocks: [08-discovery-feature, 10-web-next-wiring]
created: 2026-07-12T10:24:14Z
---

## Goal

Wire the control-plane side of the runner lifecycle: `connectWorkspace` provisions via `IRunnerProvisioner` and drives the protocol session (clone → install → scan → start preview); `workspaces` publishes `runner-status-changed` and the scan event on `IEventBus`; a realtime channel pushes stage progress + adapter-ready to the browser. This wires `core-events` and `core-realtime` end to end (PRD In scope).

## Why

Staged, honest progress is what keeps a minutes-long operation from looking hung (PRD user story 2, ui-gap §5) — and named error events (bad URL, bad token, install failure) are what make failure states diagnosable instead of a blank board (user story 5). Registry ingestion is a cross-feature reaction, so it must cross the boundary via the event bus, not a direct call (rule E0) — this story publishes; story 08 consumes.

## Done when

- `connectWorkspace` kicks off provisioning + the protocol session; the credential is decrypted only server-side and passed to the runner over the authenticated protocol channel (PRD Implementation decisions).
- `runner-status-changed` event contract lives in `workspaces` `events/`, is exported from the feature root barrel (rule E1), and is declared under `publishes` in `feature.manifest.ts`; staged events carry stage + elapsed; error events carry named causes.
- The scan event contract is likewise public + declared; the lifecycle session publishes it with the scan-result payload when the runner's scan completes.
- Realtime channel descriptor is exported from the root barrel (rule R1) and declared in the manifest; it pushes stage progress + adapter-ready to the browser; no direct `socket.io` import in the feature (rule R2).
- `getWorkspaceStatus` reflects live staged status, including named error states.
- Tests use a recording bus + scripted runner double (protocol as the contract — no assertions on runner internals).
- `pnpm conformance` event closure green; boot assertion green.
- `pnpm typecheck && pnpm lint && pnpm test && pnpm conformance && pnpm fallow:audit && pnpm coverage:diff` all pass after each task.

## In scope

- Lifecycle orchestration in `workspaces` (provision → protocol session → staged status), off the request path.
- `runner-status-changed` + scan event contracts, manifest `publishes` declarations, bus publishing.
- Realtime channel descriptor + broadcast wiring, manifest declaration.
- Named error states for bad URL / bad token / install failure.

## Out of scope

- The scan-event consumer (story 08 — discovery).
- Browser subscription UI (story 10).
- Workspace hibernation, runner fleet concerns (`workspaces-and-connections`).

## Tasks

- [ ] Run `pnpm turbo gen event` for the `runner-status-changed` contract (public from the `workspaces` root barrel; manifest `publishes` declaration) + wire the lifecycle orchestration: `connectWorkspace` provisions via `IRunnerProvisioner`, drives the protocol session (clone → install → scan → start preview) with the credential passed only over the authenticated channel, publishes staged status events (stage + elapsed) and named error events (bad URL, bad token, install failure); `getWorkspaceStatus` reflects live staged status; tests with recording bus + scripted runner double.
- [ ] Run `pnpm turbo gen event` for the scan event contract (public + manifest-declared) + publish the scan-result payload from the lifecycle session when the runner's scan completes; test asserts the publish carries the registry payload.
- [ ] Run `pnpm turbo gen realtime` for the workspace-status channel: exported channel descriptor + broadcast wiring pushing stage progress + adapter-ready to the browser; manifest declaration; handlers stay private (rule R1); tests.