feat(kiloclaw): validate openclaw config file saves

[pandemicsyn]

Summary

• Today the file editor saves every permitted file, including openclaw.json, through the generic files/write controller endpoint, which performs no installed OpenClaw schema validation. This change adds validation before an upgraded instance saves openclaw.json, preserving the user's changes and presenting an explicit Save anyway override when validation warns.
• Route openclaw.json saves through a dedicated files/write-openclaw-config endpoint only when the running controller advertises that capability. Capability gating lets not-yet-upgraded controllers keep their existing generic-save behavior; the dedicated endpoint is necessary so a controller rolled back after capability detection cannot ignore a new option on the generic endpoint and silently perform an unvalidated write.
• Validate the submitted bytes by writing a protected 0600 sibling candidate file under /root/.openclaw and invoking openclaw config validate --json with OPENCLAW_CONFIG_PATH set to that candidate. OpenClaw therefore validates the pending save rather than the live openclaw.json, while placing the file in the same directory preserves ordinary relative-include resolution.
• Carry the new write result through the Worker/Durable Object boundary and harden the controller/editor flow with ETag rechecks, protected staging artifacts, bounded diagnostics, save-race protection, and conflict-safe override UX; update the controller contract, smoke coverage, and KiloClaw changelog.

Verification

• Manual browser verification was not performed in this session because the new dialog requires an upgraded running KiloClaw instance exposing the new controller capability.
• Add manual verification details for valid-save, invalid-warning, and Save anyway behavior on an upgraded instance.

Visual Changes

Reviewer Notes

• Rollout behavior is intentional: controllers without files.write-openclaw-config continue using legacy generic files/write; capable controllers switch openclaw.json to the validated path.
• The dedicated route is a mutation-time safety boundary, not just an API convenience. If the UI sees the capability and the machine is then rolled back before Save, the dedicated call fails as unsupported instead of being accepted by an old generic writer that would ignore validation semantics and write immediately.
• Validation mechanics: the controller writes .openclaw.kiloclaw-validation-candidate.json next to the live config with mode 0600, executes openclaw config validate --json with OPENCLAW_CONFIG_PATH targeting that staged file, parses the bounded JSON result, rechecks validated bytes before committing, and cleans up staged artifacts in finally. The internal staging filename is hidden from the generic file browser/read/write surface.
• Diagnostics are returned only through authenticated config management, and an explicit Save anyway may still be rejected or restored by OpenClaw during reload/startup.

[kilo-code-bot]

Code Review Summary

Status: No Issues Found | Recommendation: Merge

Executive Summary

The incremental commit (caf0f79d2) cleanly implements spec rule 8 — serializing legacy POST /_kilo/files/write mutations of openclaw.json behind the same queue as validation-aware writes — and adds actionable POSIX error messages for staging failures. All previous findings remain resolved.

Resolved Issues (carried forward from prior review)

File	Issue	Status
services/kiloclaw/controller/src/openclaw-config-validation.ts	Outer catch silently swallowed unexpected errors	✅ Fixed — errorCode() logged via console.error
services/kiloclaw/controller/src/routes/files.ts	fs.readFileSync in hasEtagConflict() could throw unhandled ENOENT	✅ Fixed — wrapped in try/catch
services/kiloclaw/controller/src/routes/files.ts	console.warn logged raw err from backup failure (path leak)	✅ Fixed — logs only errorCode(error)
services/kiloclaw/controller/src/openclaw-config-validation.ts	Non-timeout staging failures collapsed to a single generic message	✅ Fixed — unexpectedValidationFailure() returns actionable messages for ENOSPC/EACCES/EPERM/EEXIST
services/kiloclaw/controller/src/openclaw-config-validation.ts	Recursive referencesTargetConfig could stack-overflow on deep candidates	✅ Fixed — rewritten as iterative BFS/DFS with explicit pending stack

Files Reviewed (28 files changed across all commits)

• .specs/kiloclaw-controller.md — spec rule 8 (serialization) added
• services/kiloclaw/controller/src/openclaw-config-validation.ts — iterative traversal, actionable error codes
• services/kiloclaw/controller/src/openclaw-config-validation.test.ts — staging error codes, deep nesting safety
• services/kiloclaw/controller/src/routes/files.ts — legacy write serialized via serializeAgentConfigMutation; errorCode helper; resolvesToOpenclawConfig
• services/kiloclaw/controller/src/routes/files.test.ts — serialization ordering, backup failure logging
• services/kiloclaw/controller/src/endpoint-capabilities.ts — files.write-openclaw-config capability advertised
• services/kiloclaw/controller/src/endpoint-capabilities.test.ts — capability advertisement verified
• services/kiloclaw/src/durable-objects/gateway-controller-types.ts — FileWriteResponseSchema, OpenclawFileWriteValidationSchema
• services/kiloclaw/src/durable-objects/gateway-controller-types.test.ts — schema parsing verified
• services/kiloclaw/src/durable-objects/kiloclaw-instance/gateway.ts — writeOpenclawConfigFile function
• services/kiloclaw/src/durable-objects/kiloclaw-instance/gateway.test.ts — warning forwarding tested
• services/kiloclaw/src/durable-objects/kiloclaw-instance/index.ts — DO RPC method
• services/kiloclaw/src/routes/platform.ts — POST /files/write-openclaw-config route
• services/kiloclaw/src/routes/platform-sanitize-error.test.ts — platform route tests
• services/kiloclaw/scripts/controller-entrypoint-smoke-test.sh — smoke test for invalid write response
• apps/web/src/lib/kiloclaw/kiloclaw-internal-client.ts — writeOpenclawConfigFile, FileWriteResponse type
• apps/web/src/routers/kiloclaw-router.ts — validation routing
• apps/web/src/routers/organizations/organization-kiloclaw-router.ts — validation routing
• apps/web/src/routers/organizations/organization-kiloclaw-router.test.ts — integration test
• apps/web/src/routers/admin-kiloclaw-instances-router.ts — validation routing
• apps/web/src/hooks/useKiloClaw.ts — skip cache invalidation on validation warning
• apps/web/src/hooks/useOrgKiloClaw.ts — skip cache invalidation on validation warning
• apps/web/src/app/(app)/claw/components/FileEditorPane.tsx — validation warning dialog, readOnly during save
• apps/web/src/app/(app)/claw/components/SettingsTab.tsx — capability gating
• apps/web/src/app/(app)/claw/components/WorkspaceFileEditor.tsx — prop threading
• apps/web/src/app/(app)/claw/components/changelog-data.ts — changelog entry
• apps/web/src/app/admin/components/KiloclawInstances/AdminFileEditor.tsx — admin UI gating
• apps/web/src/app/admin/components/KiloclawInstances/KiloclawInstanceDetail.tsx — capability detection

---

_{Reviewed by claude-4.6-sonnet-20260217 · 3,144,230 tokens}

_{Review guidance: REVIEW.md from base branch main}