Skip to content

Parked waits: dedicated wire events (TurnParked/TurnWoken) and a TUI heartbeat instead of synthetic Text #1857

Description

@macanderson

Problem

The parked-wait primitive (#1471) announces the park, the refusal, and the wake as synthetic AgentEvent::Text deltas (crates/stella-core/src/driver/waiting.rs). That was the deliberate slice-1 choice: stella-protocol/src/event.rs is a god file closed to growth and every new variant restales docs/wire (the wire-schema gate), so the event surface was deferred rather than rushed.

Text deltas work but are second-class: consumers cannot distinguish a park from model narration, the deck cannot render a live 'waiting 240s/1800s' heartbeat line, replay cannot skip or summarize the parked span, and stella inspect cannot attribute the wall-clock gap.

What done looks like

  • A typed event pair — either AgentEvent::TurnParked { description, poll_interval_secs, deadline_secs } / TurnWoken { reason, polls_used } next to Steered (event.rs:363 area), or a minimal StageKind::Waiting if that proves sufficient. Payload struct can live in a sibling file to keep event.rs growth to the thin variant.
  • Wire-name table rows + serde round-trip test (invariant 4); regenerate docs/wire (scripts/export-agentevent-schema.sh / the wire-schema gate).
  • Bus lifecycle names agent.turn.parked / agent.turn.woken beside AGENT_STEP_STARTED in crates/stella-core/src/bus.rs (observer-only; do NOT touch names::BLOCKING — its length is pinned by blocking_set_is_exactly_the_documented_nine).
  • The deck renders a parked state (heartbeat line or status chip) from the new events; driver/waiting.rs stops emitting the ⏳/▶ Text deltas once a renderer exists.
  • The existing witness crates/stella-core/src/driver/tests/parked_wait.rs updated to assert the typed events instead of Text contents.

Constraints

  • event.rs and bus.rs are god files at their ceilings — plan line offsets or a justified make file-size-update (AGENTS.md § God files).
  • Type doc comments on protocol structs ARE the wire contract — a /// change restales docs/wire; run the schema exporter in the same PR.
  • The park loop itself must not change behavior: this is an observability issue, not a semantics one.

Refs #1471.

Metadata

Metadata

Assignees

No one assigned

    Labels

    P2Polish — worth doing, not urgentarea:protocolstella-protocol — shared types & ports

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions