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

1. Config Diff Review Contracts

• 1.1 Add domain contracts for config diff review, proposed content, approval status, and dispatch metadata.
• 1.2 Add DTO contracts for config diff preview, approval, rejection, and dispatch responses.
• 1.3 Add validators for bounded config size, allowed file keys, expected config version, and diff content safety.
• 1.4 Add service methods for previewing and approving config writes without exposing host paths.

2. File Operation Dispatch Contracts

• 2.1 Add domain/DTO contracts for scoped file read/write requests.
• 2.2 Map file operations to platform job capabilities such as config.write, files.read, and files.write.
• 2.3 Enforce plugin/server permissions and role-scoped server access before dispatch.
• 2.4 Ensure dispatch payloads use logical file keys or artifact/input refs, not raw host paths.

3. Backend API Surface

• 3.1 Implement config diff preview route for a server instance.
• 3.2 Implement config write approval route that queues a bounded run job.
• 3.3 Implement file operation dispatch route for scoped plugin/platform file jobs.
• 3.4 Update route/protocol documentation to mark config and file dispatch implemented.

4. Frontend Integration

• 4.1 Update ServerDetailPage config write flow to call config diff preview API.
• 4.2 Update confirmation flow to call config write approval API instead of creating a generic job directly.
• 4.3 Keep explicit second confirmation before dispatching any config write.
• 4.4 Remove local-only config mutation after job dispatch; show pending platform job state instead.

5. Run Integration Prep

• 5.1 Extend run protocol job payloads to carry scoped config/file input refs.
• 5.2 Add run-side validation for allowed logical paths and bounded write payloads.
• 5.3 Add tests proving raw host paths and credentials are rejected.

6. Verification

• 6.1 Add platform tests for preview, approval, stale config version, unauthorized server access, and unsafe paths.
• 6.2 Add frontend tests for diff preview, approval, failure, and no local mutation on dispatch.
• 6.3 Run platform, run, and platform_web test/build commands and record evidence.
• 6.4 Run browser walkthrough for config diff and write approval.
• 6.5 Run scripts/check-structure.sh and record evidence.
• 6.6 Run openspec validate implement-config-write-and-file-dispatch --strict and record evidence.

Evidence

• 2026-07-06: cd platform && go test ./domain ./dto ./validator ./service ./api ./model passed after adding config diff/write contracts, validators, service methods, and API handlers.
• 2026-07-06: cd run && go test ./protocol passed after adding scoped job target/input refs and run protocol validation tests for raw host paths and raw credential refs.
• 2026-07-06: Updated platform/api/routes.md, platform/protocol/server-lifecycle.md, run/protocol/job.md, and platform_web/api/contracts.md to document implemented config diff/approval and scoped file dispatch routes/protocol payloads.
• 2026-07-06: cd platform && go test ./service ./api -run 'TestCoreServiceConfigWriteAndFileDispatchAreScoped|TestConfigWriteAndFileDispatchAPIAreScoped' passed, covering preview, approval, stale config version, unauthorized access, unsafe keys, and scoped file dispatch.
• 2026-07-06: cd platform_web && npm run typecheck passed after adding config diff/approval/file dispatch API types and client methods.
• 2026-07-06: cd platform_web && npm test -- --run api/client.test.ts pages/ServerDetailPage.test.tsx passed, covering preview/approval client requests, preview failure surfacing, platform diff mapping, no generic config.write job creation, and no local config mutation after approval dispatch.
• 2026-07-06: cd platform && go test ./... passed.
• 2026-07-06: cd run && go test ./... passed.
• 2026-07-06: cd platform_web && npm test passed with 11 files / 40 tests.
• 2026-07-06: cd platform_web && npm run build passed.
• 2026-07-06: Browser walkthrough passed using local platform 127.0.0.1:18090, Vite 127.0.0.1:5177, and headless Chrome: logged in, opened #/servers/server-walkthrough, edited config, previewed the platform diff, confirmed approval dispatch, saw the returned config.write job badge, and verified no /Users/, unix://, bearer token, raw key, password, or billing fragments were visible.
• 2026-07-06: scripts/check-structure.sh passed.
• 2026-07-06: openspec validate implement-config-write-and-file-dispatch --strict reported Change 'implement-config-write-and-file-dispatch' is valid; PostHog telemetry flush failed due restricted DNS and did not affect validation.