fix(recovery): provisional/final states, no early pins, one headline source (refs #543)

lib/ai/briefing_engine.dart

@@ -22,6 +22,7 @@ import '../coach/coach_engine.dart';
 import '../data/day_label.dart';
 import '../data/local_repository.dart';
 import '../models/metric.dart' show whyFromNote;
+import '../models/payloads.dart' show todayHeadlineOf;
 import '../ui2/screens/home_screen.dart' as ring show readinessBand;
 import 'briefing.dart';
 import 'nightly_sweep.dart';
@@ -108,7 +109,14 @@ Future<Map<String, dynamic>> collectBriefingInputs(
   }
 
   if (period == BriefingPeriod.morning) {
-    take('readiness', daily['readiness'], round: 0);
+    // The same headline Home shows: no number until today's night is final,
+    // never a held-over or still-draining one presented as this morning's.
+    take(
+        'readiness',
+        todayHeadlineOf(t)['recovery_state'] == 'final'
+            ? daily['readiness']
+            : null,
+        round: 0);
     take('resting_hr', daily['resting_hr'], round: 0);
     final hrv = _map(t['hrv']);
     take('hrv_rmssd', hrv?['rmssd'], round: 1);

lib/coach/coach_db.dart

@@ -481,18 +481,83 @@ class CoachDb {
   static Future<void> debugAssertAllowedBtrees(String sql) async =>
       _assertAllowedBtrees(await _readonly(), sql);
 
+  /// Shadow v_daily / v_metric with TEMP views whose today readiness is the
+  /// headline's. Unqualified names resolve to temp first, the temp schema is
+  /// writable on a read-only handle, and the views read the same btrees, so
+  /// neither guard layer changes. Rebuilt per query; dropped when [today] is
+  /// null.
+  static Future<void> _serveToday(
+      Database db, ({String day, num? readiness})? today) async {
+    await db.execute('DROP VIEW IF EXISTS temp.v_daily');
+    await db.execute('DROP VIEW IF EXISTS temp.v_metric');
+    if (today == null) return;
+    final day = today.day.replaceAll("'", "''");
+    final v = today.readiness?.toString() ?? 'NULL';
+    final names = [
+      for (final r in await db.rawQuery('PRAGMA main.table_info(v_daily)'))
+        '${r['name']}',
+    ];
+    final cols = [
+      for (final n in names)
+        n == 'readiness'
+            ? "CASE WHEN date = '$day' THEN $v ELSE readiness END AS readiness"
+            : '"$n"',
+    ];
+    // A pinned headline whose day has no stored readiness (the live composite
+    // abstained on a later derive) still has to read the same as Home.
+    final added = [
+      for (final n in names)
+        n == 'date' ? "'$day'" : (n == 'readiness' ? v : 'NULL'),
+    ];
+    await db.execute(
+        'CREATE TEMP VIEW v_daily AS SELECT ${cols.join(', ')} FROM main.v_daily '
+        "UNION ALL SELECT ${added.join(', ')} WHERE $v IS NOT NULL AND NOT "
+        "EXISTS (SELECT 1 FROM main.v_daily WHERE date = '$day')");
+    await db.execute('CREATE TEMP VIEW v_metric AS SELECT date, key, '
+        "CASE WHEN date = '$day' AND key = 'readiness' THEN $v ELSE value END "
+        'AS value FROM main.v_metric '
+        "UNION ALL SELECT '$day', 'readiness', $v WHERE $v IS NOT NULL AND NOT "
+        "EXISTS (SELECT 1 FROM main.v_metric WHERE date = '$day' "
+        "AND key = 'readiness')");
+  }
+
   /// Run an LLM SELECT and return compact JSON for the tool result. On a guard
   /// rejection, returns the reason (so the model fixes its query) — never throws.
-  static Future<String> runCoachSql(String llmSql, {int rowCap = 200}) async {
+  ///
+  /// [today] is today's readiness as the Home headline serves it (null until
+  /// the night is final, the pin when there is one). Today's row in v_daily /
+  /// v_metric is otherwise whatever the last derive wrote, which mid-sync is a
+  /// partial night — the 2 Home once froze on.
+  static Future<String> runCoachSql(String llmSql,
+      {int rowCap = 200, ({String day, num? readiness})? today}) async {
     String sql;
     try {
       sql = guardAndPrepare(llmSql, rowCap: rowCap);
     } on SqlGuardError catch (e) {
       return jsonEncode({'error': e.reason});
     }
+    // One query at a time: the TEMP views are per connection, so a second
+    // turn's _serveToday could otherwise swap them out between this one's
+    // setup and its query.
+    final previous = _sqlTail;
+    final turn = Completer<void>();
+    _sqlTail = turn.future;
+    await previous;
+    try {
+      return await _runServed(sql, rowCap, today);
+    } finally {
+      turn.complete();
+    }
+  }
+
+  static Future<void> _sqlTail = Future<void>.value();
+
+  static Future<String> _runServed(String sql, int rowCap,
+      ({String day, num? readiness})? today) async {
     try {
       final db = await _readonly();
       await LocalDb.refreshSessionScoreMask();
+      await _serveToday(db, today);
       await _assertAllowedBtrees(db, sql);
       // ponytail: sqflite exposes no sqlite3_progress_handler, so a slow
       // query (e.g. a giant cross-join of allowed views) can't be cancelled

lib/coach/coach_engine.dart

@@ -21,6 +21,7 @@ import 'package:path_provider/path_provider.dart';
 import '../data/day_label.dart';
 import '../data/db.dart';
 import '../data/local_repository.dart';
+import '../models/payloads.dart' show todayHeadlineOf;
 import 'coach_actions.dart';
 import 'coach_chat_completions.dart';
 import 'coach_config.dart';
@@ -787,6 +788,25 @@ class CoachEngine {
     }
   }
 
+  @visibleForTesting
+  Future<String> debugRunTool(String name, Map<String, dynamic> args) =>
+      _runTool(name, args, onItem: (_) {}, confirm: (_) async => false);
+
+  /// Today's readiness under the headline rule, for run_sql's views: the
+  /// final number or nothing. If today can't be read, today's readiness is
+  /// masked rather than left as whatever a mid-sync derive stored.
+  Future<({String day, num? readiness})?> _todayReadiness() async {
+    try {
+      final h = todayHeadlineOf(await api.getToday());
+      return (
+        day: '${h['day'] ?? todayLabel()}',
+        readiness: h['recovery_state'] == 'final' ? h['recovery'] as num? : null,
+      );
+    } catch (_) {
+      return (day: todayLabel(), readiness: null);
+    }
+  }
+
   // ── tool execution ───────────────────────────────────────────────────────────
   Future<String> _runTool(
     String name,
@@ -798,11 +818,14 @@ class CoachEngine {
       switch (name) {
         // data — one read-only SQL tool over the derived views
         case 'run_sql':
-          return await CoachDb.runCoachSql('${args['sql'] ?? ''}');
+          return await CoachDb.runCoachSql('${args['sql'] ?? ''}',
+              today: await _todayReadiness());
 
         // data — the two stores that are NOT in the SQL views. Widening
         // `coach_db`'s allow-list to reach them would trade a structural btree
         // gate for a text-level one; a typed read tool costs nothing.
+        case 'get_today':
+          return jsonEncode(todayHeadlineOf(await api.getToday()));
         case 'get_nutrition':
           return await CoachActions.nutritionDay(
               await LocalDb.instance, args['date']);
@@ -948,6 +971,7 @@ class CoachEngine {
   String _statusFor(String name, Map<String, dynamic> args) {
     switch (name) {
       case 'run_sql': return 'Querying your data…';
+      case 'get_today': return 'Reading today…';
       case 'get_nutrition': return 'Reading your food log…';
       case 'get_medications': return 'Reading your medications…';
       case 'plot_chart': return 'Plotting…';
@@ -1048,6 +1072,12 @@ class CoachEngine {
         'app computes them (a total over an entry with no numbers is a FLOOR '
         'and says so). Food is NOT in run_sql — use this.',
         {'date': {'type': 'string', 'description': 'YYYY-MM-DD, default today'}}),
+    _fn('get_today',
+        'TODAY\'s recovery, strain and sleep EXACTLY as the Home screen shows '
+        'them. Use this, not v_daily, for any question about today: v_daily\'s '
+        'today readiness is NULL until the night is final. recovery_state: final | '
+        'provisional (still finishing, may move) | night_in_progress (asleep, '
+        'no score yet) | none.', {}),
     _fn('get_medications',
         'Read the medication/supplement schedule and today\'s doses '
         '(taken/skipped/missed/upcoming). Not in run_sql — use this.', {}),

lib/coach/coach_prompt.dart

@@ -96,6 +96,9 @@ results cap at 200. If a query is rejected, read the reason and fix it.
   missing_segments) — WHOOP MG ECG readings, summary only; `category` is the
   band's. The waveform is in `get_ecg_reading(reading_id)`.
 
+TODAY's recovery, strain and sleep: call `get_today()`. It is exactly what the
+Home screen shows. Today's readiness in v_daily/v_metric is that same final
+number, or NULL while last night is still syncing; get_today says which.
 Food and medications are NOT in SQL. Use `get_nutrition(date)` and
 `get_medications()`.
 

lib/compute/derivation_engine.dart

@@ -2101,6 +2101,62 @@ bool overnightSettled({
       (nowSec != null && nowSec >= sleepOffsetSec + kOvernightGiveUpSec);
 }
 
+/// How long the band's data edge must run past a detected wake before that
+/// wake counts as CONFIRMED rather than "where the sync happened to stop".
+/// Mid-drain the stager closes the window at the newest record, so a wake
+/// sitting at the edge is no wake at all.
+// ponytail: fixed 30 min; tune against real drain timings if provisional flickers.
+const int kWakeConfirmMarginSec = 30 * 60;
+
+/// A pin is only trusted for the night whose wake is within this of its own.
+const int kPinWakeToleranceSec = 60 * 60;
+
+/// A night whose wake is before this local hour, or that slept less than
+/// [kMinPinSleepSec], is never frozen: the reported 2-instead-of-28 morning was
+/// a pin taken off the first three hours of a night still in progress.
+// ponytail: population heuristics; a night-shift sleeper never pins and reads
+// the live final value instead, which is the safe side.
+const int kMinPinWakeHour = 3;
+const int kMinPinSleepSec = 3 * 60 * 60;
+
+/// Today's recovery headline, in the one vocabulary every surface reads.
+enum RecoveryState { nightInProgress, provisional, finalReady }
+
+extension RecoveryStateWire on RecoveryState {
+  String get wire => switch (this) {
+        RecoveryState.nightInProgress => 'night_in_progress',
+        RecoveryState.provisional => 'provisional',
+        RecoveryState.finalReady => 'final',
+      };
+}
+
+/// Where today's night stands: a wake the edge has not yet run
+/// [kWakeConfirmMarginSec] past is still in progress; a confirmed wake whose
+/// window has not settled ([overnightSettled]) is provisional; settled is
+/// final. No window at all and not settled is null: nothing says the user is
+/// asleep (an unworn night reads the same until noon), so no state is claimed.
+RecoveryState? recoveryStateOf({
+  required int? wakeSec,
+  required int dataEdgeSec,
+  int? nowSec,
+}) {
+  if (overnightSettled(
+      sleepOffsetSec: wakeSec, dataEdgeSec: dataEdgeSec, nowSec: nowSec)) {
+    return RecoveryState.finalReady;
+  }
+  if (wakeSec == null) return null;
+  return dataEdgeSec >= wakeSec + kWakeConfirmMarginSec
+      ? RecoveryState.provisional
+      : RecoveryState.nightInProgress;
+}
+
+/// Whether a night is a plausible MAIN night to freeze (see [kMinPinWakeHour]).
+bool pinnableNight({required int wakeSec, int? onsetSec}) {
+  final wake = DateTime.fromMillisecondsSinceEpoch(wakeSec * 1000);
+  if (wake.hour < kMinPinWakeHour) return false;
+  return onsetSec == null || wakeSec - onsetSec >= kMinPinSleepSec;
+}
+
 /// The cross-day inputs an importer fills with its vendor's own scores.
 const _crossDayVendorScoreKeys = [
   'rhr',
@@ -2133,14 +2189,21 @@ const _crossDayVendorScoreKeys = [
   required int? liveReadiness,
   required ({String day, int value, int? wakeSec})? current,
   int? wakeSec,
+  int? onsetSec,
 }) {
+  // A pin with no wake (written by an older build) cannot say which night it
+  // is, so a night that does know its wake replaces it once that night settles.
   final sameNight = current != null &&
       current.day == today &&
-      (current.wakeSec == null ||
-          wakeSec == null ||
-          (wakeSec - current.wakeSec!).abs() < _headlineFreezeMarginSec);
-  if (sameNight) return current; // pinned; hold
-  if (overnightComplete && liveReadiness != null) {
+      (wakeSec == null ||
+          (current.wakeSec != null &&
+              (wakeSec - current.wakeSec!).abs() < kPinWakeToleranceSec));
+  final pinnable =
+      wakeSec == null || pinnableNight(wakeSec: wakeSec, onsetSec: onsetSec);
+  // A re-derive can shrink the same night below a main night (onset moved);
+  // its old pin no longer describes a pinnable night, so it is not held.
+  if (sameNight) return pinnable ? current : null; // pinned; hold
+  if (overnightComplete && pinnable && liveReadiness != null) {
     // first complete settle of this night → pin
     return (day: today, value: liveReadiness, wakeSec: wakeSec);
   }
@@ -5924,6 +5987,7 @@ class DerivationEngine {
       liveReadiness: readiness?.round(),
       current: current,
       wakeSec: day.sleepOffsetSec,
+      onsetSec: day.sleepOnsetSec,
     );
     if (next == null) return;
     // Already pinned to this exact value → skip the redundant write.
@@ -6485,14 +6549,16 @@ class DerivationEngine {
       // and tested; this only reads its inputs and emits what it returns.
       today ??= LocalDb.localDayLabelNow();
       final anchor = exceptionAnchor(cd);
-      final pin = await LocalDb.frozenHeadline();
+      // Only a pin taken on the anchor day's own night (LocalDb.headlinePinFor).
+      final pinValue =
+          anchor == null ? null : await LocalDb.headlinePinFor(anchor.date);
       final notices = planExceptionNotices(
         cd,
         today: today,
         irregularFlag: anchor == null
             ? null
             : await LocalDb.metricValueOn(anchor.date, 'irregular_rhythm_flag'),
-        pin: pin == null ? null : (day: pin.day, value: pin.value),
+        pin: pinValue == null ? null : (day: anchor!.date, value: pinValue),
         storedReadiness: anchor == null
             ? null
             : await LocalDb.metricValueOn(anchor.date, 'readiness'),