browser/openspec/changes/implement-config-write-and-file-dispatch/design.md

Context

The frontend already has a useful diff review UX, but it dispatches config writes by calling POST /jobs with capability=config.write. That bypasses platform-owned config validation, stale version checks, and scoped file semantics.

This change creates a platform service boundary for config/file dispatch. Later run worker and plugin bridge changes can execute the queued jobs using the same safe envelopes.

Goals / Non-Goals

Goals:

• Add config diff preview and approval routes.
• Validate expected config version, bounded content size, logical config keys, and server ACLs.
• Queue scoped run jobs for approved config/file operations.
• Update frontend to call approval routes rather than generic job creation.
• Keep all write operations reviewable and auditable.

Non-Goals:

• No real process execution or local file mutation in this change.
• No unrestricted file manager or raw path API.
• No plugin page bridge execution beyond shared dispatch contracts.
• No external storage backend implementation.

Decisions

Decision 1: Platform service owns write approval

Config write approval is a service method, not a frontend-generated generic job. It validates server access, config version, diff payload, and logical file key before creating a queued job.

Decision 2: File operations use logical keys and refs

Requests identify server-scoped config/file targets by logical keys or artifact/input refs. Raw absolute paths, home directories, sockets, and credentials are rejected.

Decision 3: Diff preview can be pure platform computation

The backend can compute a textual diff from current config and proposed content without dispatching work. Approval is a separate explicit call.

Decision 4: Frontend keeps second confirmation

ServerDetailPage and AI suggestion flows must keep an explicit confirmation after showing the diff. Approval dispatch happens only after that confirmation.

Risks / Trade-offs

• [Risk] Queued jobs may not execute until the real run worker change lands. Mitigation: this change verifies dispatch and state, not local mutation.
• [Risk] Diff preview duplicates frontend diff code. Mitigation: frontend diff remains display-oriented; backend diff validates dispatch input.
• [Risk] Logical file keys may be too narrow. Mitigation: keep schema extensible and add cases through future OpenSpec changes.

Migration Plan

1. Add platform contracts and validators for config diff/write and file dispatch.
2. Add API handlers and route docs.
3. Extend run protocol payload validation for scoped config/file jobs.
4. Update ServerDetailPage config and AI write flows.
5. Add backend/frontend/run tests and walkthrough.

Open Questions

• Whether approved config writes should become a first-class operation resource rather than a job-only response.
• Whether future restart/update/delete workflows should share the same approval envelope.