[codex] Structure keybindings failure diagnostics

[juliusmarminge]

Issue

Keybindings persistence failures were all tagged as parse errors with free-form details and optional causes. Validation and startup logs also emitted formatted causes, raw entries, shortcut fields, and nested issue payloads, making the logs both unbounded and difficult to correlate structurally.

Root cause

The service conflated access, decoding, encoding, and filesystem failures in one parse-oriented representation, then recovered diagnostics by serializing the original values and causes at log boundaries.

Fix

• model keybindings persistence failures as KeybindingsConfigError with a literal operation, config path, stable derived message, and required exact cause
• preserve separate encode and write causes, and retain the error as the cause when client-runtime maps initial configuration failures
• replace raw validation, shortcut, cause, and issue payloads with bounded counts, booleans, stages, indices, and stable error tags
• use catchTags at startup and interrupt-aware catchCause boundaries for the watcher
• keep malformed-document and invalid-entry user issues distinct with stable messages

This PR is stacked on #3242 so its client-side cause propagation remains intact.

Tests

• vp test apps/server/src/keybindings.test.ts packages/contracts/src/keybindings.test.ts
• vp check
• vp run typecheck

---

Note

Medium Risk
Touches config persistence, startup, and client initial-sync error mapping; behavior is mostly diagnostic but decode/write failure shapes and log content change for operators.

Overview
Replaces parse-oriented KeybindingsConfigError (formerly KeybindingsConfigParseError) with an operation literal (access, read, decode, encode, write, prepare-directory), a required cause, and a stable derived message instead of free-form detail.

Runtime and user-facing issues now use fixed copy for malformed documents vs invalid entries; validation and startup logs emit bounded metadata (stages, indices, input shape flags, cause counts/tags) and omit raw entries, formatted causes, shortcut key/when, and full issue payloads. Watcher/revalidation paths use interrupt-aware catchCause; server startup logs operation via catchTags. Client RPC maps the renamed error tag unchanged for transient connection handling.

Tests assert stable issue text, structured log fields, no sensitive command leakage, and repeatable decode failures on malformed config.

^{Reviewed by Cursor Bugbot for commit 63321c1. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Structure keybindings failure diagnostics with typed operations and safe log attributes

• Renames KeybindingsConfigParseError to KeybindingsConfigError in contracts/src/keybindings.ts and replaces the detail: string field with a typed operation literal union (access, read, decode, encode, write, prepare-directory).
• Adds structured log attribute helpers (keybindingsCauseLogAttributes, keybindingsValidationLogAttributes) that emit cause summaries and input shape metadata without embedding raw entry values or full cause strings.
• Replaces free-form issue messages with stable constants (MALFORMED_KEYBINDINGS_CONFIG_MESSAGE, INVALID_KEYBINDING_ENTRY_MESSAGE) so user-facing text no longer leaks internal cause details.
• Updates serverRuntimeStartup.ts to catch KeybindingsConfigError by tag and log operation instead of a raw cause object.
• Fixes rpc/session.ts to match the renamed error tag so keybindings errors are still mapped to a transient remote-unavailable connection error.
• Behavioral Change: KeybindingsConfigError instances now carry operation instead of detail; any code pattern-matching on the old tag KeybindingsConfigParseError or reading detail will break.

^{Macroscope summarized 63321c1.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 73722251-e0e9-439e-a67e-0ff63cb69617

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/keybindings-structured-errors

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[macroscopeapp]

Approvability

Verdict: Approved

This PR restructures keybindings error diagnostics to use structured logging attributes instead of raw error details. The actual keybinding processing behavior is unchanged - only error reporting format. Changes are well-tested and consistently propagated across the codebase.

^{You can customize Macroscope's approvability policy. Learn more.}