FE-764: Brunch<> Petrinaut stream — ephemeral orchestrator hosted SSE server

[kostandinang]

Screen Recording 2026-06-02 at 11.18.34 PM.mov (uploaded via Graphite)

Linear: FE-764 · Stack: main ← … ← ka/fe-784 (PR #160) ← ka/fe-764 (this)

Stream an executing brunch cook run into Petrinaut's read-only "actual/live" tab over one SSE connection hosted by the cook process itself. Ephemeral, localhost-only, dies with the run, persists nothing. Replay-on-connect: definition → initial_state → all firings so far → live firings → terminal.

Changes

• BrunchExecutionExport contract types + reducer (petrinaut-stream-export.ts)
• --petrinaut-fold=color|identity cook CLI flag (default identity); shared NetFolding seam between static export and live stream (cook-cli.ts, petrinaut-fold.ts, engine.ts)
• In-process stream bus with replay buffer + PetrinautEvent → BrunchExecutionExportFrame translator (petrinaut-stream-bus.ts)
• Ephemeral HTTP/SSE server over the bus, localhost-only, one GET /stream route (petrinaut-stream-server.ts)
• --petrinaut-stream cook wiring with multi-tier base-URL (CLI flag > PETRINAUT_BASE_URL env > hard fail), launcher-URL composer, auto-open via open package; server.stop() in finally (cook-cli.ts, petrinaut-launcher-url.ts, engine.ts)
• OrchestratorInput.setupPetrinautStream awaited factory hook so the SSE server is listening before initial_marking fires (types.ts, engine.ts)
• loadLocalEnvShellWins local .env loader (shell-wins precedence, only loaded when streaming)
• .env.example line for PETRINAUT_BASE_URL

Web-UI button + endpoint discovery left as a follow-up (memory/CARDS.md slice 5 sketch).

How to try it

# one-time setup
echo 'PETRINAUT_BASE_URL=https://your-petrinaut.example/import' >> .env

# run cook with live stream
brunch cook <dir> --petrinaut-stream
# → prints launcher URL, auto-opens browser

Flags:

• --petrinaut-stream — boot the SSE server + compose URL (opt-in; default off)
• --petrinaut-base-url=<url> — override env (requires --petrinaut-stream)
• --no-petrinaut-open — suppress auto-open; URL still prints (CI=true also suppresses)
• --petrinaut-fold=color|identity — projection mode (default identity; orthogonal to streaming)

Base-URL resolution: CLI flag > PETRINAUT_BASE_URL env > hard fail before any cook side effect.

Endpoints (cook-hosted, ephemeral, localhost-only)

http://127.0.0.1:<ephemeral-port>
  ├── GET     /stream  →  200 text/event-stream  (replay → live → close on terminal)
  ├── OPTIONS /stream  →  204 CORS preflight (GET, OPTIONS, *)
  └── *                →  404 Not Found

SSE frame shape (one event per BrunchExecutionExportFrame):

event: definition       data: {"version":1,"meta":…,"places":[…],"transitions":[…]}
event: initial_state    data: {"<placeId>": <number | TokenColour[]>, …}
event: transition_firing data: {"transitionId":"…","input":…,"output":…,"ts":"…"}
event: terminal         data:

Curl test guide

Grab <port> from the cook stderr, then:

URL=http://127.0.0.1:<port>/stream

curl -N $URL                       # live feed (closes on terminal frame)
curl -sI $URL                      # headers — text/event-stream + CORS
curl -sX OPTIONS -D - $URL -o-     # CORS preflight — 204
curl -sI $URL/nope                 # 404

Late-connect replay: the same curl -N $URL after the run finishes still receives the full timeline (definition → initial_state → all firings → terminal) before the connection closes.

Architecture

brunch cook  ──┐
               │   compileTopology + folding + sdcpnFile
               ▼
       ╭───────────────╮   await   ╭──────────────────────╮
       │ engine.run    │──────────▶│ setupPetrinautStream │
       │               │           │ ├─ createBus()        │
       │ emit events ──┼──────────▶│ ├─ createServer()     │
       │               │   onEvent │ ├─ server.start() (await)
       │               │           │ ├─ composeLauncherUrl()
       ╰───────────────╯           │ ├─ openUrl()          │
                                   │ ╰─ return bus.publish │
                                   ╰──────────────────────╯
                                              │
                                       SSE /stream
                                              ▼
                                      Petrinaut client

Key invariant: the SSE server is listening before the engine emits initial_marking. Enforced by an await-ordering test in engine-contract.test.ts.

Petrinaut contract alignment (verified against hashintel/hash)

• Marking ≡ InitialMarking byte-for-byte (petrinaut-core/simulation/api.ts)
• NetDefinition is a tight subset of sdcpnFileSchema; missing fields default to [] in parseSDCPNFile — can reuse the existing parser unchanged
• Field names match (colorId, inputArcs, outputArcs, lambdaType, lambdaCode, transitionKernelCode, dynamicsEnabled, differentialEquationId); schema version: 1 matches SDCPN_FILE_FORMAT_VERSION
• No live/SSE consumer exists in Petrinaut yet

Out of scope (v1)

Write-back / editing · persistent runs DB · auth · non-localhost transport · colour SDCPN (waits on Petrinaut H-6518/H-6519) · discovery endpoint · Last-Event-ID resume · SSE keep-alive.

Verification

npm run verify — 1571 tests green. Real-HTTP coverage in petrinaut-stream-server.test.ts; cook-CLI lifecycle in cook-cli.test.ts; await-ordering invariant in engine-contract.test.ts.

[kostandinang]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• FE-764: Brunch<> Petrinaut stream — ephemeral orchestrator hosted SSE server #165 👈 (View in Graphite)
• FE-784: Petrinaut export: colour-fold per-slice subnet #160
• FE-763: Petrinaut event stream — initial markings + transition firings #158
• FE-762: Petrinaut-format JSON export of the compiled net #157
• FE-761: Petri-net semantic alignment for Petrinaut visualization #156
• FE-755: Cook codebase mode for brownfield brunch #155
• FE-747: Declarative output routing for branching transitions #154
• FE-745: Epic-scoped sandbox merge for verify-epic #152
• FE-743: Petri parallel execution with resource pools and per-slice sandboxes #149
• FE-738: Petri semantic lanes with two-lane subnet and engine factory #148
• FE-730: Greenfield orchestrator POC with pi-agent dispatch #143
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[cursor]

PR Summary

Medium Risk
Opt-in localhost HTTP/SSE and engine ordering hooks change cook startup/teardown; mistakes could race first events or leak listeners, but defaults are unchanged and tests cover lifecycle and await-before-marking.

Overview
FE-764 wires an ephemeral, cook-hosted SSE live stream so Petrinaut can follow a running cook in “actual” mode. Without --petrinaut-stream, cook behavior stays the same aside from new optional flags and documentation.

Cook CLI & lifecycle: New flags include --petrinaut-stream, --petrinaut-base-url, --no-petrinaut-open, and --petrinaut-fold=color|identity (default identity). Base URL resolves CLI → PETRINAUT_BASE_URL (shell-wins .env load only when streaming) → hard fail before sandbox/plan work. createPetrinautStreamSetup starts bus + GET /stream server, prints/composes {base}?runId&mode=actual&sse=…, optionally auto-opens the browser, and server.stop() in finally.

Streaming stack: reduceBrunchExecutionExport and shared fold helpers feed an in-process replay bus (definition → initial_state → firings → terminal) and a localhost HTTP/SSE server. The engine gains setupPetrinautStream (awaited before initial_marking), createIdentityFolding, one shared NetFolding for disk export and live events, and a new net_completed terminal event on happy-path runs.

Docs/tests: .env.example, SPEC lexicon (identity fold), and PLAN/CARDS track Bristol-demo scope; broad unit/integration coverage (launcher URL, bus, server, cook-cli, engine-contract await ordering).

^{Reviewed by Cursor Bugbot for commit f043d6e. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit cf7b682. Configure here.}