browser/openspec/changes/repair-server-live-operations-console/specs/server-live-operations-console/spec.md

ADDED Requirements

Requirement: Server metrics use real samples

The system SHALL display per-server players, TPS, latency, CPU, memory, and disk from the latest authorized Run metric sample, and SHALL NOT fabricate live-looking values when no sample exists.

Scenario: Fresh metric sample exists

• WHEN a visible server has a latest Run metric sample
• THEN the server list and detail header show that sample's players, TPS, latency, CPU, memory, and disk values with the sample collection time available to the UI

Scenario: No metric sample exists

• WHEN a visible server has no persisted metric sample
• THEN the server list and detail header show pending or placeholder states instead of deterministic player, TPS, latency, CPU, memory, or disk values

Scenario: Stale metric sample exists

• WHEN a visible server's latest metric sample is older than the frontend freshness threshold
• THEN the UI marks the metrics as stale while preserving the last safe values and collection time

Requirement: Server operations refresh automatically

The system SHALL refresh server operational projections on a bounded cadence instead of requiring manual refresh for every data update.

Scenario: Server list is open

• WHEN an operator is viewing the server list
• THEN metrics and task/job status refresh automatically at a bounded interval and stop refreshing when the page unmounts

Scenario: Server detail is open

• WHEN an operator is viewing a server detail workspace
• THEN the header metrics and job state refresh automatically at a bounded interval and stop refreshing when the page unmounts

Requirement: Server list exposes live operation entry points

The server list SHALL keep 编辑部署 on server cards and SHALL provide direct live log and management terminal entry points without moving deployment editing into the detail page.

Scenario: Server card actions render

• WHEN an operator views a server card
• THEN the card includes 编辑部署, 实时日志, and 管理终端 actions using compact controls that do not reflow the card into a command tower

Scenario: Server detail actions render

• WHEN an operator views the server detail workspace
• THEN the detail header does not render an 编辑部署 action or deployment save workflow

Requirement: Live logs tail through platform cursors

The live log window SHALL read platform log streams and entries through authorized platform APIs using bounded cursor polling.

Scenario: Live log drawer opens

• WHEN an operator opens 实时日志 for a server
• THEN the UI lists authorized log streams for that server and tails selected stream entries using afterSeq cursor polling

Scenario: Live log controls are used

• WHEN an operator pauses, resumes, clears, filters, or manually refreshes live logs
• THEN the UI updates only the visible log window state and does not expose host paths, raw sockets, credentials, or Run endpoint addresses

Scenario: Run job logs are uploaded

• WHEN Platform creates a server-scoped job that Run may execute
• THEN Platform pre-registers the job stdout and stderr log streams that match Run's deterministic spool stream IDs
• AND Run log batches using the current single-line checksum and an initial global sequence number are accepted and visible through cursor queries

Scenario: Legacy persisted jobs have no log streams

• WHEN Platform starts with existing server-scoped jobs that were persisted before job log streams were auto-created
• THEN Platform recovers the missing job stdout and stderr stream metadata before log cursor recovery
• AND mediated management-program jobs recover their program stdout and stderr stream metadata as well

Requirement: Management terminal is platform-mediated

The management terminal SHALL dispatch commands only through platform-authorized plugin or lifecycle command paths and SHALL NOT provide browser-direct shell access.

Scenario: SCUM command submitted

• WHEN an operator submits a SCUM management command from the terminal
• THEN the UI dispatches the command through the existing Source RCON command API and displays safe submission/job status

Scenario: Terminal window opens

• WHEN an operator opens 管理终端
• THEN the UI presents an opaque near-full-height command console with bottom command input and quick command templates rather than a translucent narrow drawer

Scenario: Unsupported command target

• WHEN a server plugin has no supported management terminal command path
• THEN the terminal shows an unsupported state instead of exposing a raw shell or arbitrary command input

Requirement: Detail overview is removed

The server detail workspace SHALL omit the low-value overview panel and start from operational sections.

Scenario: Detail navigation renders

• WHEN an operator opens server detail
• THEN the section navigation excludes 概览 and provides operational sections such as logs, runtime controls, configuration, plugin controls, AI assistant, and operation history