browser/openspec/changes/stream-live-server-logs-sse/specs/browser-live-log-streaming/spec.md

ADDED Requirements

Requirement: Browser live logs use a platform push stream

The Platform SHALL provide a server-scoped browser log event stream that sends safe log stream metadata and log entries over Server-Sent Events.

Scenario: Operator opens live logs

• WHEN an authorized operator opens a server log view or management terminal
• THEN platform_web opens GET /api/v1/server-instances/{id}/logs/events with EventSource
• AND the view does not start a periodic /api/v1/log-streams/query polling loop

Scenario: Initial history is replayed

• WHEN the browser opens the log event stream with a bounded historyLimit
• THEN Platform replays recent stored entries for the server's log streams before sending the ready event
• AND each event contains only safe stream metadata and log entry fields

Requirement: Durable Run log ingest remains independent

Run-to-Platform log transfer SHALL remain durable HTTP batch ingest with local spool and sequence acknowledgement. Browser streaming MUST fan out only from platform-ingested log data.

Scenario: Run uploads a batch

• WHEN Run uploads a valid contiguous log batch
• THEN Platform stores it, updates the stream latest sequence, acknowledges the batch, and publishes the new entries to matching browser subscribers
• AND duplicate batch acknowledgements do not publish duplicate browser events

Requirement: Run live logs follow plugin-declared process channels

Run live terminal output SHALL come from plugin-declared log sources and the supervised process that Run started. Game-specific file logs MUST NOT be used as the default live terminal source unless the plugin declares that file source for explicit history, fallback, or backfill.

Scenario: Run starts a supervised process

• WHEN Run executes a plugin lifecycle start action in supervised mode
• THEN Run captures the process stdout and stderr into Run-owned durable capture files
• AND Run tails those capture files into durable log batch ingest using the plugin-declared process stream keys
• AND Run hides the managed Windows process window when the OS supports hidden startup

Scenario: Run restarts while the game process remains alive

• WHEN Run restarts and reloads its persisted process journal for an already-running supervised process
• THEN Run resumes tailing the Run-owned stdout/stderr capture files from persisted offsets
• AND Run does not inspect game-specific logs such as SCUM.log to synthesize terminal output

Requirement: Browser log streaming uses platform session authorization

The log event stream SHALL be authorized by the current platform user session and server access rules. Plugins and browser code MUST NOT receive Run session tokens, component keys, host paths, raw credentials, or direct Run socket information.

Scenario: Unauthorized user subscribes

• WHEN a user without access opens a server log event stream
• THEN Platform rejects the request using the existing authorization error behavior
• AND no log entries or stream metadata are sent

Requirement: Reverse proxies forward log events without buffering

The deployed platform_web reverse proxy SHALL forward the log event route without response buffering and with a long read timeout so idle log periods do not force browser polling.

Scenario: Nginx proxies SSE

• WHEN Nginx forwards /api/v1/server-instances/{id}/logs/events
• THEN buffering is disabled for that location
• AND the route does not require WebSocket upgrade headers