Merge pull request #167 from n8bar/claude/issue-163-watcher-liveness

fix(support): watcher health reads the watcher's own run stamp, not payment recency

Author: n8bar

app/Console/Commands/WatchInvoicePayments.php

@@ -5,6 +5,7 @@
 use App\Models\Invoice;
 use App\Services\DonationPaymentSyncService;
 use App\Services\InvoicePaymentSyncService;
+use App\Support\WatcherLiveness;
 use Illuminate\Console\Command;
 
 class WatchInvoicePayments extends Command
@@ -70,6 +71,10 @@ public function handle(): int
         if (! $this->option('invoice')) {
             $donations = $this->donationSyncService->syncPending();
             $this->info("Checked {$donations['checked']} donation addresses, {$donations['paid']} newly paid.");
+
+            // A single-invoice run is not a full sweep, so only unfiltered
+            // runs count as liveness for the support dashboard (#163).
+            WatcherLiveness::recordCompletedRun();
         }
 
         return Command::SUCCESS;

app/Http/Controllers/Support/SupportDashboardController.php

@@ -4,6 +4,7 @@
 
 use App\Http\Controllers\Controller;
 use App\Models\User;
+use App\Support\WatcherLiveness;
 use Illuminate\Contracts\View\View;
 use Illuminate\Http\Request;
 use Illuminate\Support\Facades\DB;
@@ -70,16 +71,21 @@ private function monitoringPanel(): array
             ->where('is_adjustment', false)
             ->max(DB::raw('COALESCE(detected_at, created_at)'));
 
+        // Liveness comes from the watcher's own run stamp, never from payment
+        // recency — a quiet hour is not a dead watcher, and a payment landing
+        // says nothing about the watcher since (#163). No stamp reads stale.
         $staleMinutes = config('support.watcher_stale_minutes', 60);
-        $watcherStale = $lastPaymentAt !== null
-            && now()->diffInMinutes($lastPaymentAt, false) < -$staleMinutes;
+        $watcherLastRanAt = WatcherLiveness::lastCompletedRunAt();
+        $watcherStale = $watcherLastRanAt === null
+            || $watcherLastRanAt->lt(now()->subMinutes($staleMinutes));
 
         return [
-            'queue_depth'     => $queueDepth,
-            'recent_failures' => $recentFailures,
-            'last_payment_at' => $lastPaymentAt,
-            'watcher_stale'   => $watcherStale,
-            'stale_minutes'   => $staleMinutes,
+            'queue_depth'         => $queueDepth,
+            'recent_failures'     => $recentFailures,
+            'last_payment_at'     => $lastPaymentAt,
+            'watcher_last_ran_at' => $watcherLastRanAt,
+            'watcher_stale'       => $watcherStale,
+            'stale_minutes'       => $staleMinutes,
         ];
     }
 }

app/Support/WatcherLiveness.php

@@ -0,0 +1,31 @@
+<?php
+
+namespace App\Support;
+
+use Illuminate\Support\Carbon;
+use Illuminate\Support\Facades\Cache;
+
+/**
+ * When the payment watcher last completed a full sweep.
+ *
+ * Lives in the cache (database store) because the watcher runs in the
+ * scheduler container while the support dashboard renders in the app
+ * container — WorkerHeartbeat's files are container-local by design and
+ * cannot cross that boundary (#163).
+ */
+class WatcherLiveness
+{
+    public const CACHE_KEY = 'watcher:last_completed_run_at';
+
+    public static function recordCompletedRun(): void
+    {
+        Cache::forever(self::CACHE_KEY, now()->toIso8601String());
+    }
+
+    public static function lastCompletedRunAt(): ?Carbon
+    {
+        $value = Cache::get(self::CACHE_KEY);
+
+        return $value ? Carbon::parse($value) : null;
+    }
+}

docs/specs/SUPPORT_ACCESS.md

@@ -87,6 +87,8 @@ The owner setting copy should communicate all of these points in plain language:
   - that the view is read-only support access
   - when the access expires
 - If the grant expires or is revoked while support is navigating, the next request must deny access cleanly.
+- The service-health panel reports watcher liveness from the watcher's own last completed run, readable from any container serving the dashboard.
+- Payment recency is separate context on the panel and never stands in for watcher liveness; a watcher with no recorded run reads as needing attention, not as healthy.
 
 ## Data Model Requirements
 The owner record must persist enough state to determine whether support access is currently valid.

resources/views/support/dashboard.blade.php

@@ -175,22 +175,29 @@ class="w-72 max-w-full rounded-md border-gray-300 text-sm shadow-sm focus:border
 
                     {{-- Watcher health --}}
                     <div class="px-6 py-5">
-                        <p class="text-xs font-semibold uppercase tracking-wider text-gray-500 dark:text-slate-400">Watcher last seen</p>
-                        @if ($monitoring['last_payment_at'])
+                        <p class="text-xs font-semibold uppercase tracking-wider text-gray-500 dark:text-slate-400">Watcher</p>
+                        @if ($monitoring['watcher_last_ran_at'])
                             <p class="mt-1 text-sm font-semibold
                                 {{ $monitoring['watcher_stale'] ? 'text-amber-600 dark:text-amber-400' : 'text-gray-900 dark:text-white' }}">
-                                {{ \Illuminate\Support\Carbon::parse($monitoring['last_payment_at'])->setTimezone(config('app.timezone'))->toDayDateTimeString() }}
+                                {{ $monitoring['watcher_last_ran_at']->setTimezone(config('app.timezone'))->toDayDateTimeString() }}
                             </p>
                             @if ($monitoring['watcher_stale'])
                                 <p class="mt-0.5 text-xs text-amber-600 dark:text-amber-400">
-                                    No activity in over {{ $monitoring['stale_minutes'] }} minutes — worth checking.
+                                    No completed run in over {{ $monitoring['stale_minutes'] }} minutes — worth checking.
                                 </p>
                             @else
-                                <p class="mt-0.5 text-xs text-green-600 dark:text-green-400">recent</p>
+                                <p class="mt-0.5 text-xs text-green-600 dark:text-green-400">on schedule</p>
                             @endif
                         @else
-                            <p class="mt-1 text-sm text-gray-400 dark:text-slate-500">No on-chain payments recorded yet.</p>
+                            <p class="mt-1 text-xs text-amber-600 dark:text-amber-400">No completed run recorded yet — worth checking.</p>
                         @endif
+                        <p class="mt-2 text-xs text-gray-500 dark:text-slate-400">
+                            @if ($monitoring['last_payment_at'])
+                                Last on-chain payment: {{ \Illuminate\Support\Carbon::parse($monitoring['last_payment_at'])->setTimezone(config('app.timezone'))->toDayDateTimeString() }}
+                            @else
+                                No on-chain payments recorded yet.
+                            @endif
+                        </p>
                     </div>
 
                 </div>

tests/Feature/SupportMonitoringTest.php

@@ -6,7 +6,9 @@
 use App\Models\Invoice;
 use App\Models\InvoicePayment;
 use App\Models\User;
+use App\Support\WatcherLiveness;
 use Illuminate\Foundation\Testing\RefreshDatabase;
+use Illuminate\Support\Facades\Cache;
 use Tests\TestCase;
 
 class SupportMonitoringTest extends TestCase
@@ -110,52 +112,76 @@ public function test_failures_older_than_24_hours_are_excluded(): void
         $this->assertStringNotContainsString('old@example.com', $response->getContent());
     }
 
-    public function test_watcher_healthy_shows_recent_label(): void
+    /**
+     * #163: watcher liveness comes from the watcher's own run stamp, so a
+     * quiet hour with no payments must not read as a stale watcher.
+     */
+    public function test_watcher_reads_healthy_from_fresh_run_stamp_despite_no_payments(): void
     {
         $agent = $this->supportAgent();
-        $issuer = User::factory()->create();
-        $invoice = $this->makeInvoice($issuer);
-
-        InvoicePayment::create([
-            'invoice_id'    => $invoice->id,
-            'txid'          => 'tx-mon-health',
-            'sats_received' => 10000,
-            'is_adjustment' => false,
-            'detected_at'   => now()->subMinutes(10),
-            'confirmed_at'  => now()->subMinutes(9),
-            'usd_rate'      => 50000,
-            'fiat_amount'   => 5.00,
-        ]);
+        WatcherLiveness::recordCompletedRun();
 
         $this->actingAs($agent)
             ->get(route('support.dashboard'))
             ->assertOk()
-            ->assertSee('recent');
+            ->assertSee('on schedule')
+            ->assertDontSee('worth checking');
     }
 
-    public function test_watcher_staleness_flag_triggers_past_threshold(): void
+    public function test_watcher_reads_stale_from_old_run_stamp_despite_recent_payment(): void
     {
         $agent = $this->supportAgent();
         config(['support.watcher_stale_minutes' => 30]);
 
+        Cache::forever(WatcherLiveness::CACHE_KEY, now()->subMinutes(65)->toIso8601String());
+
         $issuer = User::factory()->create();
         $invoice = $this->makeInvoice($issuer);
 
         InvoicePayment::create([
             'invoice_id'    => $invoice->id,
-            'txid'          => 'tx-mon-stale',
+            'txid'          => 'tx-mon-dead-watcher',
             'sats_received' => 10000,
             'is_adjustment' => false,
-            'detected_at'   => now()->subMinutes(60),
-            'confirmed_at'  => now()->subMinutes(59),
+            'detected_at'   => now()->subMinutes(5),
+            'confirmed_at'  => now()->subMinutes(4),
             'usd_rate'      => 50000,
             'fiat_amount'   => 5.00,
         ]);
 
         $this->actingAs($agent)
             ->get(route('support.dashboard'))
             ->assertOk()
-            ->assertSee('No activity in over 30 minutes');
+            ->assertSee('No completed run in over 30 minutes');
+    }
+
+    public function test_watcher_with_no_recorded_run_reads_as_needing_attention(): void
+    {
+        $agent = $this->supportAgent();
+
+        $this->actingAs($agent)
+            ->get(route('support.dashboard'))
+            ->assertOk()
+            ->assertSee('No completed run recorded yet');
+    }
+
+    public function test_watch_command_records_a_completed_run_stamp(): void
+    {
+        $this->assertNull(WatcherLiveness::lastCompletedRunAt());
+
+        $this->artisan('wallet:watch-payments')->assertExitCode(0);
+
+        $this->assertNotNull(WatcherLiveness::lastCompletedRunAt());
+    }
+
+    public function test_single_invoice_run_does_not_record_a_completed_run_stamp(): void
+    {
+        $issuer = User::factory()->create();
+        $invoice = $this->makeInvoice($issuer);
+
+        $this->artisan('wallet:watch-payments', ['--invoice' => $invoice->id])->assertExitCode(0);
+
+        $this->assertNull(WatcherLiveness::lastCompletedRunAt());
     }
 
     public function test_adjustment_payments_excluded_from_watcher_health(): void
@@ -166,7 +192,7 @@ public function test_adjustment_payments_excluded_from_watcher_health(): void
         $issuer = User::factory()->create();
         $invoice = $this->makeInvoice($issuer);
 
-        // Only an adjustment — should not count as watcher activity
+        // Only an adjustment — the payment-recency reading counts on-chain rows only
         InvoicePayment::create([
             'invoice_id'    => $invoice->id,
             'txid'          => 'tx-adj',
@@ -190,6 +216,8 @@ public function test_healthy_state_renders_all_three_indicators_cleanly(): void
         $issuer = User::factory()->create();
         $invoice = $this->makeInvoice($issuer);
 
+        WatcherLiveness::recordCompletedRun();
+
         InvoicePayment::create([
             'invoice_id'    => $invoice->id,
             'txid'          => 'tx-mon-ok',
@@ -206,7 +234,8 @@ public function test_healthy_state_renders_all_three_indicators_cleanly(): void
             ->assertOk()
             ->assertSee('Service Health')
             ->assertSee('no failures')
-            ->assertSee('recent');
+            ->assertSee('on schedule')
+            ->assertSee('Last on-chain payment');
     }
 
     public function test_no_payments_recorded_yet_renders_cleanly(): void