fix(core,server): security audit fixes + response-size hardening

Fixes 2 security bugs found via deep audit, closes 2 more targeted
gaps from the same audit's follow-up, and ships the pagination
default flip that audit had left pending sign-off:

- fingerprint_edit_lines/edit_symbol/hunks: switch to length-prefixed
  (netstring-style) field encoding, closing a delimiter-injection
  preimage collision that could forge a fingerprint match and skip
  HIGH_RISK_REQUIRES_INDEPENDENT_REVIEW via a stale approved review.
- run_migrations_from: read-decide-write is now atomic per step
  (fresh PRAGMA user_version inside BEGIN IMMEDIATE, never-regress
  guard on both the per-step and final stamp), closing a TOCTOU that
  could let a concurrent/earlier writer's version get stamped
  backwards below the real physical schema.
- compute_touch_risk: multi-hunk signature-escalation gap -- a
  signature rewritten by several hunks that jointly cover it, with no
  single hunk covering it alone, previously escaped detection. New
  compute_touch_risk_with_reconstruction reuses the real apply_hunks
  splice edit_lines_impl_gated already computes (for
  validate_syntax_diff) instead of a new diff algorithm; every other
  caller is unaffected (they only ever construct one whole-range
  hunk, for which the original heuristic is already exact).
- claim_approved_matching: pending_reviews approvals are now one-shot
  -- atomically consumes the matching row instead of a bare read, so
  one human approval authorizes exactly one write.
- SourceParams/UnderstandParams.max_lines: default flips to 300 when
  the JSON key is omitted (explicit null still unlimited), based on
  live measurement (p99=260 production symbols, 14 outliers over
  300). Also fixes understand()'s suggested_next, which never checked
  for truncation before pointing at edit_context.
- SymbolsBatchParams.lean + schemars description overrides on 4
  shared structs trim response/schema size.

Full regression coverage for every fix; cargo test/clippy/fmt clean.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: Your Name

crates/calm-core/src/analysis/coverage.rs

@@ -21,6 +21,31 @@ impl CoverageData {
         };
         (line_start..=line_end).any(|ln| file_cov.contains(&ln))
     }
+
+    /// P1 (audit follow-up, 2026-08-23): fraction of `[line_start,
+    /// line_end]` (inclusive) that has SOME recorded execution, as
+    /// `covered / total_lines_in_range`. `0.0` when the file has no
+    /// coverage data at all or the range is empty/inverted. Distinct from
+    /// `is_covered`'s any-line-at-all question -- that answers "did this
+    /// range ever run", correct for `compute_dead_code_confidence`'s
+    /// liveness check, but too lenient for a caller asking "is this edit
+    /// adequately tested": a 50-line range with exactly 1 covered line
+    /// reads as fully `is_covered`, hiding that the other 49 lines are
+    /// genuinely untested. Callers deciding whether to escalate risk
+    /// should compare this ratio against their own threshold instead.
+    pub fn coverage_ratio(&self, abs_path: &str, line_start: i64, line_end: i64) -> f64 {
+        if line_end < line_start {
+            return 0.0;
+        }
+        let total = (line_end - line_start + 1) as f64;
+        let Some(file_cov) = self.covered_lines.get(abs_path) else {
+            return 0.0;
+        };
+        let covered = (line_start..=line_end)
+            .filter(|ln| file_cov.contains(ln))
+            .count() as f64;
+        covered / total
+    }
 }
 
 // Defined in `indexer::coverage_paths`, not here: `indexer::refresh` also
@@ -332,6 +357,32 @@ mod tests {
         assert!(!cov.is_covered("/bar.py", 1, 100));
     }
 
+    /// P1 (audit follow-up, 2026-08-23): coverage_ratio must report the
+    /// real fraction, not just any-line-at-all -- this is the fact
+    /// touches_uncovered_code's threshold check now relies on to catch a
+    /// mostly-untested hunk that is_covered alone would have missed (1
+    /// covered line out of a 50-line range read as "fully covered").
+    #[test]
+    fn test_coverage_ratio() {
+        let mut lines = HashSet::new();
+        lines.insert(5);
+        lines.insert(10);
+        let cov = CoverageData {
+            source: "lcov".to_string(),
+            covered_lines: HashMap::from([("/foo.py".to_string(), lines)]),
+        };
+        // 2 covered lines (5, 10) out of a 10-line range [1, 10].
+        assert_eq!(cov.coverage_ratio("/foo.py", 1, 10), 0.2);
+        // Fully covered single-line range.
+        assert_eq!(cov.coverage_ratio("/foo.py", 10, 10), 1.0);
+        // No overlap at all.
+        assert_eq!(cov.coverage_ratio("/foo.py", 20, 25), 0.0);
+        // Unknown file -> 0.0, same convention as is_covered.
+        assert_eq!(cov.coverage_ratio("/bar.py", 1, 100), 0.0);
+        // Inverted range is defensively 0.0, not a panic.
+        assert_eq!(cov.coverage_ratio("/foo.py", 10, 1), 0.0);
+    }
+
     #[test]
     fn test_normalize_path_strips_dot_segments_when_not_existing() {
         let dir = tempfile::tempdir().unwrap();

crates/calm-core/src/authority/mod.rs

@@ -13,8 +13,9 @@ pub mod snapshot;
 
 pub use pending_review::{
     AgentRelayOutcome, NewPendingReview, PENDING_REVIEW_DEFAULT_TTL_SECS, PendingReview,
-    approve_pending_review, decide_via_agent_relay, decline_pending_review, find_approved_matching,
-    get_pending_review, insert_pending_review, list_pending_reviews,
+    approve_pending_review, claim_approved_matching, decide_via_agent_relay,
+    decline_pending_review, find_approved_matching, get_pending_review, insert_pending_review,
+    list_pending_reviews,
 };
 pub use receipt::{ApprovalReceipt, insert_approval_receipt};
 pub use review::{

crates/calm-core/src/authority/pending_review.rs

@@ -289,6 +289,53 @@ pub fn find_approved_matching(
     .optional()
 }
 
+/// Bug (2026-08-23 audit, pending_review not one-shot): the write-gate
+/// claim `edit_lines_impl_gated` should use instead of a bare
+/// `find_approved_matching` -- atomically transitions the matching
+/// unexpired `status = 'approved'` row to `status = 'consumed'` and
+/// returns it, so ONE human approval authorizes exactly ONE write, not an
+/// unlimited number of them for up to `PENDING_REVIEW_DEFAULT_TTL_SECS`.
+/// Previously a plain `SELECT` with no consumption meant any later call
+/// that happened to reproduce the identical `(path, fingerprint)` --
+/// e.g. the file legitimately cycling back to a byte-identical state via
+/// an unrelated edit-then-revert within the TTL window -- would silently
+/// reuse a stale human decision instead of asking again.
+///
+/// The `UPDATE ... WHERE status = 'approved'` is the actual atomic claim:
+/// if two callers somehow race on the exact same row, SQLite serializes
+/// the two `UPDATE`s and only the first can actually flip the row, so at
+/// most one caller's `rows_affected` is 1 -- no separate TOCTOU window to
+/// close with an explicit transaction (unlike the migration-stamp race
+/// fixed the same day, which needed one because it was read-decide-write
+/// across multiple statements; here the claim IS the one statement). The
+/// preceding `find_approved_matching` call is just a read to pick a
+/// candidate to try -- if it was concurrently claimed or expired before
+/// the `UPDATE` runs, `rows_affected == 0` and this honestly returns
+/// `None`, exactly as if no match had ever existed, and the caller falls
+/// through to requiring a fresh review.
+pub fn claim_approved_matching(
+    conn: &Connection,
+    path: &str,
+    fingerprint: &str,
+) -> rusqlite::Result<Option<PendingReview>> {
+    let Some(candidate) = find_approved_matching(conn, path, fingerprint)? else {
+        return Ok(None);
+    };
+    let now = now_epoch_secs();
+    let updated = conn.execute(
+        "UPDATE pending_reviews SET status = 'consumed' \
+         WHERE review_id = ?1 AND status = 'approved' AND expires_at > ?2",
+        params![candidate.review_id, now],
+    )?;
+    if updated == 0 {
+        return Ok(None);
+    }
+    Ok(Some(PendingReview {
+        status: "consumed".to_string(),
+        ..candidate
+    }))
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -355,6 +402,51 @@ mod tests {
         assert_eq!(found.review_id, id);
     }
 
+    #[test]
+    fn claim_approved_matching_consumes_the_row_so_a_second_claim_no_longer_matches() {
+        // Bug (2026-08-23 audit, pending_review not one-shot): a plain
+        // find_approved_matching (a SELECT) let the SAME approved row
+        // authorize an unlimited number of writes for up to
+        // PENDING_REVIEW_DEFAULT_TTL_SECS -- claim_approved_matching must
+        // atomically consume it instead, so a second attempt at the exact
+        // same (path, fingerprint) no longer matches.
+        let conn = state_conn();
+        let id =
+            insert_pending_review(&conn, &new_review("edit_lines", "a.py", "sha256:abc")).unwrap();
+        assert!(approve_pending_review(&conn, &id, "cli_manual_review").unwrap());
+
+        let first = claim_approved_matching(&conn, "a.py", "sha256:abc")
+            .unwrap()
+            .expect("an approved, unexpired, matching row must be claimable once");
+        assert_eq!(first.review_id, id);
+        assert_eq!(first.status, "consumed");
+
+        let second = claim_approved_matching(&conn, "a.py", "sha256:abc").unwrap();
+        assert_eq!(
+            second, None,
+            "the same approval must not authorize a second write"
+        );
+
+        // The row itself is really gone from the approved pool, not just
+        // invisible to this one function -- the plain read-only lookup
+        // must agree.
+        assert_eq!(
+            find_approved_matching(&conn, "a.py", "sha256:abc").unwrap(),
+            None
+        );
+        let got = get_pending_review(&conn, &id).unwrap().unwrap();
+        assert_eq!(got.status, "consumed");
+    }
+
+    #[test]
+    fn claim_approved_matching_misses_cleanly_when_nothing_is_approved() {
+        let conn = state_conn();
+        assert_eq!(
+            claim_approved_matching(&conn, "a.py", "sha256:abc").unwrap(),
+            None
+        );
+    }
+
     #[test]
     fn find_approved_matching_misses_on_a_different_fingerprint() {
         // Content-addressed: the proposal changed since review was opened.

crates/calm-core/src/db/state_migrations.rs

@@ -942,42 +942,63 @@ pub(crate) fn run_migrations_from(
     migrations: &[StateMigration],
     target: i64,
 ) -> Result<(), StateMigrationError> {
-    let on_disk: i64 = conn.query_row("PRAGMA user_version", [], |r| r.get(0))?;
-    let mut current = if on_disk == 0 {
-        BASELINE_VERSION
-    } else {
-        on_disk
-    };
-
-    while current < target {
-        let step = match migrations.iter().find(|m| m.from == current) {
-            Some(s) => s,
-            None => {
-                return Err(StateMigrationError::MissingMigration {
+    loop {
+        conn.execute_batch("BEGIN IMMEDIATE")?;
+        let step_result = (|| -> Result<bool, StateMigrationError> {
+            // Fresh read INSIDE this transaction -- closes the TOCTOU a bare
+            // read-before-the-loop + unconditional-stamp-after-the-loop had
+            // (2026-08-23 audit, Bug B): a concurrent OTHER process (e.g. a
+            // newer binary migrating this same file further) could commit
+            // its own advance between an outer read taken once before a
+            // loop and a later unconditional stamp, silently REGRESSING
+            // user_version below what that process already established --
+            // even though the newer schema's DDL is still physically
+            // present, defeating `refuse_if_schema_newer`'s downgrade guard
+            // for every process that opens the file afterward. Re-reading
+            // here, inside our own BEGIN IMMEDIATE, sees the true latest
+            // committed value (no other writer can commit while we hold
+            // this lock), so `current` is never stale by the time we
+            // decide what (if anything) to write.
+            let on_disk: i64 = conn.query_row("PRAGMA user_version", [], |r| r.get(0))?;
+            let current = if on_disk == 0 {
+                BASELINE_VERSION
+            } else {
+                on_disk
+            };
+            if current >= target {
+                // Nothing left for THIS call to do -- possibly because a
+                // concurrent process already finished it. Never regress a
+                // version someone else already stamped higher; only bring
+                // a genuinely unstamped/behind file up to `target`.
+                if on_disk < target {
+                    conn.pragma_update(None, "user_version", target)?;
+                }
+                return Ok(true);
+            }
+            let step = migrations.iter().find(|m| m.from == current).ok_or(
+                StateMigrationError::MissingMigration {
                     from: current,
                     target,
-                });
-            }
-        };
-        debug_assert_eq!(
-            step.to,
-            step.from + 1,
-            "state.db migrations must be consecutive single-version steps (got {}: {} -> {})",
-            step.name,
-            step.from,
-            step.to
-        );
-
-        conn.execute_batch("BEGIN IMMEDIATE")?;
-        let step_result = (|| -> Result<(), StateMigrationError> {
+                },
+            )?;
+            debug_assert_eq!(
+                step.to,
+                step.from + 1,
+                "state.db migrations must be consecutive single-version steps (got {}: {} -> {})",
+                step.name,
+                step.from,
+                step.to
+            );
             (step.apply)(conn)?;
             conn.pragma_update(None, "user_version", step.to)?;
-            Ok(())
+            Ok(false)
         })();
         match step_result {
-            Ok(()) => {
+            Ok(done) => {
                 conn.execute_batch("COMMIT")?;
-                current = step.to;
+                if done {
+                    return Ok(());
+                }
             }
             Err(e) => {
                 // Undoes both the DDL and (if it was reached) the
@@ -988,13 +1009,6 @@ pub(crate) fn run_migrations_from(
             }
         }
     }
-
-    // Always stamp explicitly, even when zero migrations ran -- a fresh or
-    // `user_version == 0` file must still come out of this function stamped
-    // to `target`, not left at its raw on-disk value, or the downgrade
-    // guard has nothing to check next time.
-    conn.pragma_update(None, "user_version", target)?;
-    Ok(())
 }
 
 #[cfg(test)]
@@ -1213,6 +1227,32 @@ mod tests {
         ));
     }
 
+    #[test]
+    fn run_migrations_from_never_regresses_a_version_already_stamped_higher() {
+        // Bug B (2026-08-23 audit): simulates the concurrent-process race
+        // deterministically, without real threads -- a newer binary (or
+        // just an earlier, faster call) already advanced this exact file
+        // to version 3 (with real physical schema to match) before THIS
+        // call, whose own `target` is only 2, ever got to look. The OLD
+        // code read `user_version` once, decided `current(2) < target(2)`
+        // was false so no step ran, then unconditionally stamped `target`
+        // (2) anyway at its final line -- regressing the file from 3 back
+        // to 2 even though its real schema was already ahead. The fix must
+        // leave an already-higher on-disk version untouched.
+        let conn = fresh_conn();
+        conn.pragma_update(None, "user_version", 3).unwrap();
+
+        let migrations: [StateMigration; 0] = [];
+        run_migrations_from(&conn, &migrations, 2).unwrap();
+
+        assert_eq!(
+            user_version(&conn),
+            3,
+            "a version a concurrent/earlier writer already stamped higher must never be \
+             regressed down to this call's own (now-stale) target"
+        );
+    }
+
     #[test]
     fn registered_v1_to_v2_migration_creates_the_new_tables_and_stamps_version() {
         let conn = fresh_conn();