功能修改

openspec/changes/implement-game-client-bridge-and-scum-operations/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-07-20

openspec/changes/implement-game-client-bridge-and-scum-operations/design.md

@@ -0,0 +1,98 @@
+## Context
+
+The current platform already has the foundation for plugin runtime declarations, Client Manager build/deploy/control/update/rollback/uninstall, component-key registration, heartbeat, safe status projections, log ingest, artifact records, config diff review, remote access declarations, and backup metadata. The SCUM example manifest also declares a `custom-client` lifecycle and `game-client.bridge` capability, but the bridge is only a placeholder: there is no durable command domain, snapshot ingest/query model, bridge service, repository, DTO, or API surface.
+
+The reference SCUM repositories contain useful behavior: a companion client that can interact with the game window and OCR, server operations and command flows, SCUM log parsing, player/squad/vehicle/flag state, backups, restarts, rewards, events, and database-backed queries. They also contain patterns that must not be copied into this platform: shared credentials, insecure TLS skip, arbitrary terminal commands, arbitrary SQL, raw host paths, direct run sockets, direct cloud credentials, and SCUM business rules embedded into executor code.
+
+The intended ownership model is:
+
+- `game.scum` plugin owns SCUM semantics: pages, schemas, commands, players, squads, vehicles, flags, logs, database query templates, backup/restart/event policy, and `scum_client` companion behavior.
+- Platform owns generic product infrastructure: auth, permission checks, durable queue, scheduling, audit, persistence, safe projections, and plugin-page APIs.
+- Independent Run owns generic privileged execution only: process supervision, bounded file/SQLite/archive operations, and artifact transfer. No SCUM-specific source tree is added to this repository.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Introduce a generic Game Client Bridge that supports authenticated companion clients, durable commands, command claims, acknowledgements, results, cancellation, expiry, idempotency, fencing, and typed snapshot ingestion/query.
+- Add SCUM plugin operations that declare commands, snapshots, permissions, approval levels, page contracts, and companion-client expectations.
+- Align the SCUM plugin manifest and the real `scum_client` model so generated packages use Platform Client Manager registration/session and bridge APIs instead of legacy `/api/v1/scum-clients/*` shared-token endpoints.
+- Preserve channel isolation: game-client bridge traffic does not block run control, jobs, log ingest, or artifact transfer.
+- Keep raw credentials, host paths, SQL text, direct sockets, and component secrets out of plugin pages and browser-visible DTOs.
+
+**Non-Goals:**
+
+- Do not implement SCUM business logic inside independent Run.
+- Do not add a `run/` source tree back to this repository.
+- Do not expose arbitrary shell, arbitrary SQL, generic remote desktop, direct cloud storage credentials, QQ/SMS/music/Douyin/provider workflows, host sales, billing, or unrelated SaaS marketplace features.
+- Do not auto-ban or auto-punish players from heuristics in the first bridge phase; moderation begins as evidence, alerts, and operator-approved actions.
+- Do not require all legacy SCUM robot features to ship in one implementation pass.
+
+## Decisions
+
+### Decision: Separate Game Client Bridge from Run lifecycle channels
+
+Platform will add a separate bridge domain and API for companion-client commands and snapshots. It will not reuse Run job leases, log batches, artifact chunks, or lifecycle control endpoints for game-window operations.
+
+Rationale: the existing run-contracts already state that the optional game client bridge is separate from run lifecycle, control registration, job handling, log ingest, and artifact transport. Keeping it separate prevents game commands or large snapshots from delaying heartbeat, job acknowledgement, log upload, or artifact transfer.
+
+Alternative considered: model every companion action as a Run job. That would blur operator-visible game operations with machine-side lifecycle execution, make SCUM commands look like generic privileged jobs, and increase the risk of leaking host/executor details into plugin pages.
+
+### Decision: Reuse Client Manager identity for companion clients
+
+`scum_client` will be deployed and supervised through the existing Client Manager lifecycle. Bridge APIs will require a valid component session bound to server instance, plugin, profile key, artifact, key generation, deployment generation, capabilities, and expiry.
+
+Rationale: the platform already has component-key generation, registration signatures, session revocation, heartbeat, health projection, and staged update/rollback. Extending from that identity avoids introducing a second secret model.
+
+Alternative considered: preserve legacy shared `SCUMClientCredential` and `/api/v1/scum-clients/hello|heartbeat|commands|results|snapshots`. That pattern cannot meet current security boundaries because one shared credential can outlive deployment generations, cannot fence stale packages cleanly, and was paired with insecure TLS behavior in the reference client.
+
+### Decision: Let plugins declare SCUM semantics, not Platform or Run
+
+The `game.scum` plugin will declare command catalog entries, snapshot schemas, query templates, page contracts, permission scopes, and approval levels. Platform will validate and persist these declarations, enforce auth/audit/lifecycle mechanics, and expose safe bridge APIs. Run will only execute generic capabilities requested by Platform.
+
+Rationale: the user correctly pointed out that these are SCUM plugin features. Putting SCUM semantics in Platform or Run would make the generic layers harder to reuse for other games and would violate the repository boundary that Run stays independent.
+
+Alternative considered: add first-class SCUM domain services directly to Platform. That would produce faster short-term UI but would freeze SCUM-specific concepts into platform core.
+
+### Decision: Use typed templates for database and file operations
+
+SCUM database reads will be exposed as plugin-declared read-only query templates with typed parameters and bounded result schemas. Backups and restart automation will be declared as SCUM logical policies but executed through generic Platform/Run operations.
+
+Rationale: the reference projects include useful SCUM.db and maintenance behavior, but arbitrary SQL or raw path access is not acceptable in the plugin-page boundary. Template declarations preserve common workflows while keeping operations reviewable and enforceable.
+
+Alternative considered: expose a generic SQL console or file browser to plugin pages. That would violate the existing platform rule that pages never receive DSNs, credentials, host paths, or direct Run endpoints.
+
+### Decision: Start moderation as evidence and approval flows
+
+Duplicate IP, mine, unlock, trade, and suspicious activity signals will initially create typed evidence, alerts, and suggested actions. Destructive or punitive actions require explicit operator approval and audit.
+
+Rationale: the reference robot contains powerful heuristics, but automatic punishments have high false-positive and abuse risk. Approval-first flows are safer and still make the signals useful.
+
+Alternative considered: directly port automatic punish/ban behavior. That is out of scope for the first bridge and would require separate governance requirements.
+
+## Risks / Trade-offs
+
+- Bridge queue and snapshot persistence can become broad quickly -> Mitigation: phase implementation around a small generic state machine, bounded payload sizes, schema versioning, retention, and server-scoped query filters.
+- Real `scum_client` currently reads embedded `config.yaml` and does not parse the manifest's `--config config.json` argument -> Mitigation: update the SCUM plugin declaration and companion bootstrap together; support a generated config format that carries Platform registration settings without raw secrets in browser-visible DTOs.
+- Snapshot schemas may drift from actual SCUM output -> Mitigation: version schemas, persist raw diagnostic excerpts only in redacted server-side records when needed, and keep plugin validators close to parser code.
+- Remote read-only SQLite transport currently has gaps around payload/input propagation -> Mitigation: implement bridge database templates only after the remote access request path preserves declared inputs end to end.
+- Frontend scope could sprawl into the whole legacy admin product -> Mitigation: first pages should cover operationally central SCUM surfaces only: client health, commands, players/sessions, vehicles/squads/flags, semantic logs, and maintenance.
+- Long-running commands may conflict with deployment updates or session resets -> Mitigation: command claims include component session, deployment generation, lease expiry, and fencing tokens; stale sessions cannot ack or complete current commands.
+
+## Migration Plan
+
+1. Add Platform bridge domain, DTOs, repository interfaces, persistence, service methods, validators, routes, and tests.
+2. Extend plugin manifest/schema validation for game-client command catalogs, snapshot schemas, approval levels, and page bridge contracts.
+3. Update the SCUM example plugin manifest from local proof placeholders to a real `game.scum` lifecycle/client declaration aligned with generated config and Client Manager registration.
+4. Add SCUM plugin page/API types and initial UI surfaces using safe Platform projections.
+5. Adapt `scum_client` packaging expectations so it registers and heartbeats through Client Manager sessions and uses bridge command/snapshot APIs.
+6. Add typed SCUM log parsing, database query templates, backup/restart declarations, and event/reward flows in later task groups after the bridge is verified.
+7. Run `openspec validate implement-game-client-bridge-and-scum-operations --strict`, focused backend/frontend/plugin tests, and `scripts/check-structure.sh`.
+
+Rollback is feature-flag-like by declaration: servers without a deployed compatible Client Manager or without a plugin-declared bridge catalog see disabled bridge actions and no command dispatch. Existing run lifecycle, log ingest, and plugin registry behavior remains intact.
+
+## Open Questions
+
+- Which exact SCUM operations should be enabled in the first UI pass: read-only snapshots plus announcements, or also gifts/rewards/restarts?
+- Should bridge command payload/result bodies be stored entirely in Platform DB for the first pass, or split larger artifacts to the artifact channel once payloads exceed a small threshold?
+- Does `scum_client` remain in the external SCUM repository with generated packaging metadata, or should a minimal companion fixture be added under the plugin example for local smoke tests only?

openspec/changes/implement-game-client-bridge-and-scum-operations/proposal.md

@@ -0,0 +1,30 @@
+## Why
+
+The SCUM companion client, robot workflows, and run-side helpers contain useful server-operations behavior, but their current shape mixes SCUM product semantics with ad hoc transport, credentials, host paths, and executor responsibilities. We need a first-party bridge that lets `game.scum` own SCUM-specific commands, snapshots, and pages while Platform and Run provide only generic secure infrastructure.
+
+## What Changes
+
+- Add a generic Game Client Bridge capability for durable, authenticated component commands, command lifecycle tracking, cancellation, expiry, idempotency, fencing, result recording, and versioned snapshot ingest/query.
+- Add SCUM plugin operations on top of that bridge: command catalog, snapshot schemas, page contracts, permissions, and approval levels for players, squads, vehicles, flags, sessions, logs, database query templates, backups, restarts, and events.
+- Adapt the real `scum_client` model into a plugin-owned companion component that registers through the Platform Client Manager path, heartbeats securely, claims bridge commands, returns results, and uploads typed snapshots.
+- Keep independent Run free of SCUM business logic. Run may deploy, supervise, execute bounded process/file/SQLite/archive capabilities, and report lifecycle state, but SCUM semantics remain declared by the plugin and mediated by Platform.
+- Replace unsafe legacy patterns from the reference projects with platform-mediated equivalents: no arbitrary terminal, no arbitrary SQL, no raw host paths, no shared credentials, no direct run sockets, no insecure TLS skip, and no script-based arbitrary URL self-update.
+
+## Capabilities
+
+### New Capabilities
+
+- `game-client-bridge`: Defines the platform bridge for authenticated companion clients, durable command queues, command result flow, cancellation/expiry semantics, snapshot ingestion, snapshot querying, retention, and audit trails.
+- `scum-operations`: Defines the SCUM plugin-owned operational model, including typed commands, typed snapshots, pages, permissions, approval policy, log semantics, database query templates, backup/restart policies, and client integration requirements.
+
+### Modified Capabilities
+
+- None.
+
+## Impact
+
+- Backend Platform: new API routes, DTOs, domain types, repositories, services, persistence models, validation rules, permissions, and audit events for the Game Client Bridge.
+- Platform Web: bridge-aware SCUM operation views that preserve the magical-girl crystal-moonlight console direction and do not receive raw credentials or host paths.
+- Plugins: `plugins/examples/scum-server-plugin` gains real `game.scum` command catalogs, snapshot schemas, page contracts, permissions, and lifecycle/client declarations aligned with the real companion client.
+- Companion Client: `scum_client` behavior is migrated from legacy shared-token endpoints to Platform Client Manager registration/session and bridge command/snapshot APIs.
+- Run Executor: no SCUM-specific source is added to this repository; Run remains an independent generic executor for declared process, file, SQLite, artifact, and packaging operations.

openspec/changes/implement-game-client-bridge-and-scum-operations/specs/game-client-bridge/spec.md

@@ -0,0 +1,119 @@
+## ADDED Requirements
+
+### Requirement: Component sessions authenticate bridge access
+
+The Platform SHALL require every Game Client Bridge request from a companion client to use a valid component session issued through the Client Manager registration flow.
+
+#### Scenario: Valid component session uses bridge capability
+
+- **WHEN** a deployed companion client registers with the current component key generation, deployment generation, and `game-client.bridge` capability
+- **THEN** the Platform accepts bridge requests for the bound server instance, plugin, profile key, artifact, and session expiry window
+
+#### Scenario: Stale component session is rejected
+
+- **WHEN** a companion client uses a session from a revoked key generation, expired session, old deployment generation, or undeclared bridge capability
+- **THEN** the Platform rejects the bridge request without returning raw key material or internal secret locations
+
+### Requirement: Commands are durable and fenced
+
+The Platform SHALL persist Game Client Bridge commands with lifecycle state, idempotency key, expiry, priority, declared command type, payload reference or inline bounded payload, target server instance, plugin, requester, approval state, claim lease, fencing token, and audit metadata.
+
+#### Scenario: Operator queues declared bridge command
+
+- **WHEN** an authorized operator queues a command declared by the active plugin bridge catalog
+- **THEN** the Platform stores the command as pending, records an audit event, and exposes only safe command status to plugin pages
+
+#### Scenario: Duplicate idempotency key is reused
+
+- **WHEN** the same requester submits the same command type with the same idempotency key for the same server instance
+- **THEN** the Platform returns the existing command instead of creating a duplicate command
+
+#### Scenario: Expired command is not claimed
+
+- **WHEN** a pending command has passed its expiry time before a companion client claims it
+- **THEN** the Platform marks the command expired and prevents later claim or execution
+
+### Requirement: Companion clients claim and complete commands
+
+The Platform SHALL let authenticated companion clients claim pending bridge commands in bounded batches and complete them only with the active claim lease and fencing token.
+
+#### Scenario: Client claims pending command batch
+
+- **WHEN** an online companion client polls for bridge commands for its bound server instance and profile key
+- **THEN** the Platform returns only eligible pending commands, marks them claimed, assigns leases, and includes fencing tokens
+
+#### Scenario: Stale claim cannot complete command
+
+- **WHEN** a companion client submits an ack or result with an expired lease, stale fencing token, or mismatched component session
+- **THEN** the Platform rejects the update and leaves the current command state protected from stale completion
+
+#### Scenario: Command result is recorded
+
+- **WHEN** the active claimant completes a command with a success or failure result
+- **THEN** the Platform stores sanitized result metadata, updates command status, records completion time, and emits an audit event
+
+### Requirement: Operators can cancel pending or claimed commands
+
+The Platform SHALL allow authorized operators to cancel bridge commands that are not already terminal and SHALL prevent cancelled commands from being executed or completed as successful.
+
+#### Scenario: Pending command is cancelled
+
+- **WHEN** an authorized operator cancels a pending command
+- **THEN** the Platform marks the command cancelled and excludes it from future claim batches
+
+#### Scenario: Claimed command is cancelled before completion
+
+- **WHEN** an authorized operator cancels a claimed command
+- **THEN** the Platform records the cancellation and rejects later success results from the old claim
+
+### Requirement: Snapshots are versioned and typed
+
+The Platform SHALL ingest Game Client Bridge snapshots only when their type, schema version, sequence, source component, payload shape, and retention policy match active plugin declarations.
+
+#### Scenario: Client uploads declared snapshot
+
+- **WHEN** a companion client uploads a snapshot that matches a declared snapshot type and schema version
+- **THEN** the Platform stores it with server instance, plugin, profile key, source session, sequence, observed time, and retention metadata
+
+#### Scenario: Snapshot sequence is stale
+
+- **WHEN** a companion client uploads a snapshot with a sequence older than or equal to the latest accepted sequence for the same stream
+- **THEN** the Platform rejects or quarantines the stale snapshot according to validation policy and does not replace the current projection
+
+#### Scenario: Plugin page queries snapshots
+
+- **WHEN** an authorized plugin page requests snapshots for an owned server instance
+- **THEN** the Platform returns bounded safe projections without raw component secrets, host paths, direct sockets, or unbounded raw dumps
+
+### Requirement: Bridge traffic is isolated from Run channels
+
+The Platform SHALL keep Game Client Bridge command and snapshot traffic separate from Run control heartbeat, job acknowledgement, log ingest, and artifact transfer channels.
+
+#### Scenario: Large snapshot ingestion does not block control
+
+- **WHEN** a companion client uploads a large but allowed snapshot payload
+- **THEN** Run control heartbeat, job acknowledgement, and log upload remain independently serviceable through their own channels
+
+#### Scenario: Bridge unavailable does not disable server lifecycle
+
+- **WHEN** the Game Client Bridge service is unavailable or no companion client is online
+- **THEN** existing Run lifecycle actions, log ingest, artifact transfer, and Client Manager lifecycle projections continue to operate
+
+### Requirement: Browser-visible bridge DTOs are safe projections
+
+The Platform SHALL expose only safe bridge declarations, command statuses, results, snapshots, availability reasons, and audit references to plugin pages.
+
+#### Scenario: Plugin page loads bridge state
+
+- **WHEN** a plugin page loads bridge state for a server instance
+- **THEN** the response excludes raw credentials, component keys, sessions, DSNs, host paths, direct Run endpoints, sockets, and storage provider credentials
+
+### Requirement: Bridge records are retained and audited
+
+The Platform SHALL apply bounded retention to bridge commands, results, snapshots, and audit references while preserving enough metadata for operator review and troubleshooting.
+
+#### Scenario: Retention job expires old bridge records
+
+- **WHEN** bridge records exceed configured retention limits
+- **THEN** the Platform expires or compacts old records without exposing deleted payloads through plugin page APIs
+

openspec/changes/implement-game-client-bridge-and-scum-operations/specs/scum-operations/spec.md

@@ -0,0 +1,127 @@
+## ADDED Requirements
+
+### Requirement: SCUM plugin owns SCUM operation semantics
+
+The `game.scum` plugin SHALL declare SCUM-specific commands, snapshot schemas, log event schemas, database query templates, permissions, approval levels, page contracts, and policy labels.
+
+#### Scenario: Platform loads SCUM bridge declarations
+
+- **WHEN** the Platform registers the SCUM plugin manifest
+- **THEN** it validates the declared SCUM operation catalog and stores safe declarations without adding SCUM business logic to independent Run
+
+#### Scenario: Unknown SCUM command is rejected
+
+- **WHEN** a plugin page or operator attempts to queue a SCUM command that is not declared by the active SCUM plugin catalog
+- **THEN** the Platform rejects the command before it reaches a companion client
+
+### Requirement: SCUM companion client uses Platform identity and bridge APIs
+
+The SCUM companion client SHALL register and heartbeat through the Platform Client Manager component-session flow and SHALL use Game Client Bridge command and snapshot APIs for game-window interaction.
+
+#### Scenario: Generated client package starts with platform config
+
+- **WHEN** a SCUM Client Manager package is generated and deployed
+- **THEN** its runtime configuration aligns with the actual companion client bootstrap and includes only the material required to register with Platform through the current component-key generation
+
+#### Scenario: Legacy shared-token endpoint is not used
+
+- **WHEN** a SCUM companion client exchanges commands or snapshots with Platform
+- **THEN** it does not use legacy shared-token `/api/v1/scum-clients/hello`, `/heartbeat`, `/commands`, `/results`, or `/snapshots` endpoints
+
+#### Scenario: Insecure TLS skip is not allowed
+
+- **WHEN** the SCUM companion client connects to Platform
+- **THEN** it must not disable certificate verification through an unconditional insecure TLS setting
+
+### Requirement: SCUM snapshots cover core operational state
+
+The SCUM plugin SHALL define typed snapshot schemas for at least online sessions, players, squads, vehicles, flags or territories, and companion health diagnostics.
+
+#### Scenario: Player snapshot is ingested
+
+- **WHEN** the SCUM companion client uploads a declared player or online-session snapshot
+- **THEN** Platform stores a versioned safe projection that plugin pages can query by server instance and observed time
+
+#### Scenario: Vehicle and flag snapshots are ingested
+
+- **WHEN** the SCUM companion client uploads declared vehicle, squad, flag, or territory snapshots
+- **THEN** Platform validates the schema version and sequence before updating the current projection
+
+### Requirement: SCUM command catalog is bounded and permissioned
+
+The SCUM plugin SHALL expose only declared, typed, permission-scoped game commands such as announcements, player lookup, reward delivery, event actions, maintenance preparation, and safe companion diagnostics.
+
+#### Scenario: Operator queues announcement
+
+- **WHEN** an authorized operator queues a declared SCUM announcement command
+- **THEN** Platform records the requester, approval state, command payload, idempotency key, and audit event before the companion client can claim it
+
+#### Scenario: Risky command requires approval
+
+- **WHEN** a SCUM command is marked as risky, destructive, economy-affecting, or punitive
+- **THEN** Platform requires the declared approval level before making the command claimable
+
+### Requirement: SCUM moderation begins as evidence and review
+
+The SCUM plugin SHALL model suspicious duplicate IP, unlock, mine, trade, kill, admin, and economy signals as evidence, alerts, and operator-reviewed recommendations by default.
+
+#### Scenario: Suspicious event is parsed
+
+- **WHEN** SCUM semantic log parsing detects a suspicious event pattern
+- **THEN** Platform records a typed evidence event or alert without automatically banning, punishing, or modifying the player
+
+#### Scenario: Operator approves punitive action
+
+- **WHEN** an operator chooses a punitive SCUM action from a recommendation
+- **THEN** Platform applies the command catalog permission and approval rules before dispatching any companion command
+
+### Requirement: SCUM logs are parsed into typed events
+
+The SCUM plugin SHALL define typed semantic log events for chat, login, logout, kill, trade, mine, unlock, admin, and performance records.
+
+#### Scenario: Chat log event is parsed
+
+- **WHEN** SCUM chat log lines are ingested
+- **THEN** Platform stores typed chat events that plugin pages can filter by player, time range, and server instance
+
+#### Scenario: Performance log event updates metrics
+
+- **WHEN** SCUM performance log lines are ingested
+- **THEN** Platform maps FPS and entity counts into bounded metric projections and alert inputs
+
+### Requirement: SCUM database access uses read-only templates
+
+The SCUM plugin SHALL declare read-only SCUM.db query templates with typed parameters, bounded result schemas, and permission scopes instead of exposing arbitrary SQL.
+
+#### Scenario: Operator runs player lookup template
+
+- **WHEN** an authorized operator runs a declared player lookup query template
+- **THEN** Platform dispatches a bounded read-only request and returns only the declared result columns
+
+#### Scenario: Arbitrary SQL is requested
+
+- **WHEN** a plugin page submits SQL text that is not backed by a declared query template
+- **THEN** Platform rejects the request and does not dispatch it to Run or the companion client
+
+### Requirement: SCUM backup and restart policy remains plugin-declared
+
+The SCUM plugin SHALL declare backup scopes, retention policy, restart schedules, warning announcements, and update-check policy as SCUM operational policy while Platform and Run execute only generic jobs.
+
+#### Scenario: Scheduled restart is prepared
+
+- **WHEN** a SCUM restart schedule reaches its warning window
+- **THEN** Platform queues declared SCUM announcement commands and generic lifecycle actions according to plugin policy and operator approvals
+
+#### Scenario: Backup is requested
+
+- **WHEN** an authorized operator requests a SCUM backup
+- **THEN** Platform records the logical SCUM backup scope and dispatches generic archive/artifact operations without exposing raw host paths or storage credentials to the plugin page
+
+### Requirement: SCUM operation pages use safe Platform projections
+
+The SCUM plugin pages SHALL render bridge state, snapshots, commands, logs, backup/restart policy, and review flows using Platform-mediated DTOs only.
+
+#### Scenario: SCUM operations page loads
+
+- **WHEN** a user opens the SCUM operations page for a server instance
+- **THEN** the page can display safe bridge status, companion health, current snapshots, command availability, and recent results without receiving raw secrets, host paths, DSNs, direct Run sockets, or component session material

openspec/changes/implement-game-client-bridge-and-scum-operations/tasks.md

@@ -0,0 +1,53 @@
+## 1. Platform Bridge Foundation
+
+- [x] 1.1 Add Game Client Bridge domain types for commands, command states, claims, results, cancellations, snapshots, snapshot streams, retention metadata, and audit references.
+- [x] 1.2 Add bridge DTOs and validation rules for queue, claim, ack/result, cancel, snapshot ingest, snapshot query, and safe browser projections.
+- [x] 1.3 Add repository interfaces and in-memory or durable store implementations for bridge commands, snapshots, stream sequence tracking, and retention queries.
+- [x] 1.4 Add service methods for command creation, idempotency reuse, claim leasing, fencing-token checks, terminal result handling, cancellation, expiry, and audit recording.
+- [x] 1.5 Add component-session authorization checks so only current Client Manager sessions with `game-client.bridge` can claim commands or upload snapshots.
+
+## 2. Platform API Surface
+
+- [x] 2.1 Add operator-facing API routes for listing bridge declarations/status, queueing declared commands, cancelling commands, reading command results, and querying snapshots.
+- [x] 2.2 Add companion-facing API routes for claiming command batches, acknowledging commands, posting results, uploading snapshots, and reporting bridge diagnostics.
+- [x] 2.3 Ensure bridge routes expose only safe projections and never expose component keys, sessions, secret refs, host paths, DSNs, direct Run endpoints, sockets, or storage credentials.
+- [x] 2.4 Add bridge retention and expiry reconciliation paths for old commands, old results, stale claims, and expired snapshots.
+
+## 3. Plugin Manifest and SDK Contracts
+
+- [x] 3.1 Extend plugin manifest schema and validation for game-client command catalogs, snapshot schemas, approval levels, permissions, retention policy, and page bridge contracts.
+- [x] 3.2 Extend plugin SDK/API types so plugin pages can call Platform-mediated bridge actions without receiving raw executor or component secrets.
+- [x] 3.3 Fix remote-access request input propagation needed by declared read-only database templates before enabling SCUM.db query operations.
+- [x] 3.4 Add manifest/schema tests for rejected arbitrary SQL, arbitrary shell, raw paths, undeclared commands, unsafe capabilities, and missing approval metadata.
+
+## 4. SCUM Plugin Operations
+
+- [x] 4.1 Update the SCUM plugin manifest from local proof placeholders to real `game.scum` operation declarations for lifecycle, client manager, bridge commands, snapshots, logs, and pages.
+- [x] 4.2 Align SCUM Client Manager packaging/config declarations with the real companion client bootstrap instead of nonexistent `configs/client.template.json`, `config.json`, and unsupported `--config` assumptions.
+- [x] 4.3 Add typed SCUM snapshot schemas for online sessions, players, squads, vehicles, flags or territories, and companion health diagnostics.
+- [x] 4.4 Add bounded SCUM command catalog entries for announcements, safe diagnostics, player lookup, reward/event flows, restart preparation, and maintenance actions with permissions and approval levels.
+- [x] 4.5 Add read-only SCUM.db query template declarations with typed parameters and bounded result schemas.
+- [x] 4.6 Add SCUM semantic log event declarations for chat, login, logout, kill, trade, mine, unlock, admin, and performance events.
+
+## 5. Frontend Operations Surface
+
+- [x] 5.1 Add Platform Web API client/types for bridge declarations, command status, command results, snapshot projections, approval state, and bridge diagnostics.
+- [x] 5.2 Add SCUM operations page contracts and route wiring through the existing plugin page bridge model.
+- [x] 5.3 Build the first SCUM operations UI for companion health, command queue/results, players/sessions, vehicles/squads/flags, semantic logs, and maintenance policy using safe Platform projections.
+- [x] 5.4 Preserve the `platform_web` magical-girl crystal-moonlight operations-console style and avoid page-local fixed decorative effects outside `MagicalParticleLayer`.
+
+## 6. Companion Client Integration
+
+- [x] 6.1 Define the generated companion config shape used by Platform Client Manager registration and bridge APIs without exposing browser-visible raw secrets.
+- [x] 6.2 Adapt the SCUM companion client integration path away from legacy shared-token `/api/v1/scum-clients/*` endpoints toward Platform component-session registration, heartbeat, command claim/result, and snapshot upload.
+- [x] 6.3 Remove unconditional insecure TLS behavior from the companion integration path and add tests or checks for secure transport defaults.
+- [x] 6.4 Add local smoke fixtures or documentation showing how a compatible `scum_client` package claims a command and uploads a typed snapshot.
+
+## 7. Tests and Verification
+
+- [x] 7.1 Add backend unit tests for bridge idempotency, claim leasing, fencing, cancellation, expiry, result recording, component-session authorization, safe projections, and snapshot sequence handling.
+- [x] 7.2 Add plugin manifest validation tests for the SCUM operation declarations and unsafe legacy-pattern rejection.
+- [x] 7.3 Add frontend tests for SCUM bridge API typing, disabled availability reasons, command approval states, and safe rendering without secrets.
+- [x] 7.4 Run focused Go and frontend tests covering changed packages.
+- [x] 7.5 Run `openspec validate implement-game-client-bridge-and-scum-operations --strict`.
+- [x] 7.6 Run `scripts/check-structure.sh`.