Explicit Partial-Success Semantics

When an API operation can be “partially successful” (or yields an empty but non-error outcome), encode that distinction explicitly in the response/protocol so callers can take correct next actions.

Apply this standard:

• Never use a plain Success with an empty result to represent distinct conditions like “requested line range is beyond EOF”.
• If the system must return per-item results while still reporting per-item problems, extend the Success shape with a dedicated field (e.g., missing_ranges: [...] / failed_ranges: [...]) instead of forcing an all-or-nothing Failure or misusing an existing field with different semantics (e.g., treating “range missing” as “file missing”).
• Keep server/protocol status modeling explicit and stateful: expose machine-readable state enums and failure categories; prefer bulk initialization/status RPCs over repeated per-entity polling when clients need initial state.

Example pattern (server response shape):

// Instead of: ReadFilesResult::Success { files: vec![] }
// Use something like:
ReadFilesResult::Success {
  files: vec![/* successfully read files */],
  missing_ranges: vec![
    MissingRange { path: "a.txt", line_range: (1891, 2090) }
  ],
}

// Or, if per-file success is granular:
ReadFilesResult::Success {
  per_file: vec![
    PerFileResult::Ok { path: "a.txt", segments: vec![...] },
    PerFileResult::MissingRange { path: "b.txt", requested: (1891, 2090), eof: 1237 },
  ]
}

This keeps the API truthful, prevents misleading UI states, and lets agent/client logic “course-correct” without breaking the ability to return other successfully retrieved items.