cronwatch 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4717ad1d0fcfb080755faed7d4f018257f1b382e3076ab3e16d6830d9f985732
-  data.tar.gz: a907c315c80b237b09eb40087cfa7f28f5ed261494686b00f4c6df3710afeaf1
+  metadata.gz: b8af9eac18f781dcf622c274e6f3e44370a4373d0721215ba2928f133d3b36bd
+  data.tar.gz: 20577e3909253de5b132c4fba48654b9176a593efc8c5c86caf85845fe16c1c7
 SHA512:
-  metadata.gz: 201500f44422be56f7c741a3dfd200ef7b0eabd893b3ea7466b8c3504f36d834f07d2a3a41e55d5035255abba46c0462498c9920c8c0d12e19843f9e3d8b1daa
-  data.tar.gz: c6fd81253765bd342f698cfa93ff66a87b13e20fee82d7d6c48972d8c25769b8cb48db1971bc082cfb0fc1660f1900535279135169514615724668b1aa21e0c4
+  metadata.gz: 3f29e87d9cd6b09776a1c744c147b29ac20f6311072e2f7eb7d16b5ba4eaf4f29b3cbb204567badb4f655af12224fb308923a7e6b1f8e4189fd9b42db2df2079
+  data.tar.gz: 8c3e6d1326f545a5fa453235a385814351c0575927a024ed0fc341cb6a2e639e996856ec4ca96eb2f4e674b0d90a70789a431514b9c4e7f140cb917efd12de0d

data/README.md

@@ -2,7 +2,7 @@
 
 Cron and scheduled-job monitoring that lives inside your Ruby or Rails app. Wrap a job once; every run is recorded in a database you already have, and you are told when a run is missed, fails, gets stuck, runs slow or goes over budget. No server to run, no account to make.
 
-This is the Ruby port of [`@cronwatch/sdk`](https://www.npmjs.com/package/@cronwatch/sdk): the same rules, the same alert text and the same stored rows, so a Ruby process and a Node process can share one database, and [`@cronwatch/mcp`](https://www.npmjs.com/package/@cronwatch/mcp) works against either.
+This is the Ruby port of [`@cronwatch/sdk`](https://www.npmjs.com/package/@cronwatch/sdk): the same rules, the same alert text and the same stored rows, so a Ruby process can share one database with a Node, Python, PHP, Go or Rust process, and [`@cronwatch/mcp`](https://www.npmjs.com/package/@cronwatch/mcp) works against any of them.
 
 Docs: [cronwatch.dev/docs/rails](https://cronwatch.dev/docs/rails/) and [cronwatch.dev/docs/ruby](https://cronwatch.dev/docs/ruby/)
 
@@ -20,13 +20,13 @@ Ruby 3.2 or newer; the Rails integration is tested on Rails 7.2, 8.0 and 8.1. Th
 | `cronwatch` | the client, the memory store, and the Slack, Discord, webhook, console, email (Resend, Postmark, SendGrid, Mailgun, SES), Twilio and error tracker (Sentry, Honeybadger, Datadog, Rollbar, Bugsnag, New Relic) channels | |
 | `cronwatch/pg_cron` | `Cronwatch::Sources::PgCron`, which watches pg_cron jobs through an ActiveRecord or pg connection | |
 | `cronwatch/active_record` | the ActiveRecord store | `activerecord` |
-| `cronwatch/rails` | the Railtie, `Cronwatch::ActiveJob`, `Cronwatch::CheckJob`, the `cronwatch:check` task, the install generator | `railties`, `activejob` |
+| `cronwatch/rails` | the Railtie, `Cronwatch::ActiveJob`, `Cronwatch::CheckJob`, `Cronwatch::Web`, the `cronwatch:check` task, the install generator | `railties`, `activejob` |
 | `cronwatch/sidekiq` | `Cronwatch::Sidekiq` for `Sidekiq::Job` classes, its server middleware, `Cronwatch::Sidekiq::CheckWorker` | `sidekiq` 7 or newer |
 | `cronwatch/scheduler` | schedules read from Solid Queue's or sidekiq-cron's config, `Cronwatch.declare_from_scheduler!` | |
 | `cronwatch/web` | the dashboard and JSON API as a Rack app | `rack` |
 | `cronwatch/triage/anthropic` | Claude triage | `anthropic` |
 
-In a Rails app, `gem "cronwatch"` also loads `cronwatch/rails` and `cronwatch/scheduler` (Bundler requires it after Rails), `cronwatch/sidekiq` when Sidekiq is in the bundle, and the ActiveRecord store on first use. `cronwatch/web` and `cronwatch/triage/anthropic` are always required by hand.
+In a Rails app, `gem "cronwatch"` also loads `cronwatch/rails`, `cronwatch/web` and `cronwatch/scheduler` (Bundler requires it after Rails), `cronwatch/sidekiq` when Sidekiq is in the bundle, and the ActiveRecord store on first use. `cronwatch/triage/anthropic` is always required by hand, and so is `cronwatch/web` outside Rails.
 
 ## Plain Ruby
 
@@ -64,7 +64,7 @@ run.finish                          # or run.fail(error); finish("text") and fin
 
 Neither raises for the store: failures go to `on_error`, and a finish of a run already finished, not found, or of another job records nothing and returns nil. A run is judged once, however many processes finish it at once, and a store that fails during `finish` leaves the handle active to finish again. A run never finished is marked stuck after the job's `timeout`.
 
-Client options: `store`, `alerts`, `triage`, `cron_secret`, `retention` (default `"30d"`), `defaults`, `redact` (default: blank values that look like secrets; `false` keeps output as logged, or pass a callable), `deliver` (`:now` by default; `:check` queues alerts for another process's check to send, for a worker that cannot reach Slack), `on_error` and `now`. Methods: `job`, `run`, `resume_run`, `check`, `start`/`stop`, `silence(name, for: "2h")`/`unsilence`, `forget`, `jobs`, `jobs_with_runs`, `job_summary`, `runs`, `get_run`, `defined_jobs`, `close`. [cronwatch.dev/docs/ruby](https://cronwatch.dev/docs/ruby/#api) has each one.
+Client options: `store`, `alerts`, `triage`, `cron_secret`, `retention` (default `"30d"`), `defaults`, `sources` (where runs the process does not wrap come from, such as pg_cron), `redact` (default: blank values that look like secrets; `false` keeps output as logged, or pass a callable), `deliver` (`:now` by default; `:check` queues alerts for another process's check to send, for a worker that cannot reach Slack), `on_error` and `now`. Methods: `job`, `run`, `resume_run`, `record_run`, `check`, `start`/`stop`, `silence(name, for: "2h")`/`unsilence`, `forget`, `jobs`, `jobs_with_runs`, `job_summary`, `runs`, `get_run`, `defined_jobs`, `close`. [cronwatch.dev/docs/ruby](https://cronwatch.dev/docs/ruby/#api) has each one.
 
 ## Rails
 
@@ -130,7 +130,7 @@ reads the class's one entry in Solid Queue's `config/recurring.yml` (the section
 
 ### Scheduling the check
 
-Failures are caught as they happen, but a run that never started or never finished can only be noticed by looking. `Cronwatch::CheckJob` looks: it loads `app/jobs` (and `app/workers`) when the app does not eager load, declares every monitored job and runs the check. Run it every five minutes.
+Failures are caught as they happen, but a run that never started or never finished can only be noticed by looking. `Cronwatch::CheckJob` looks: it loads `app/jobs` (and `app/workers` and `app/sidekiq`) when the app does not eager load, declares every monitored job and runs the check. Run it every five minutes.
 
 Solid Queue:
 
@@ -168,7 +168,7 @@ Rails.application.routes.draw do
 end
 ```
 
-Set `CRONWATCH_TOKEN` to a long random string and open `/cronwatch?token=<it>` once; the browser keeps a cookie. Without a token, while `RAILS_ENV` or `RACK_ENV` is `development` or `test`, it makes a token of its own and prints a sign-in link to standard output on its first request (open it once; unless `origin:` is set or the request's host is loopback, the link leaves the host out, since a client chooses it); anywhere else it answers 503. To rely on the app's own sign in, mount it behind that (Devise's `authenticate` block, or a routing constraint) and pass `token: nil`. The URLs, JSON shapes, headers and CSRF rules are the SDK's, so the MCP server reads it unchanged. The request's origin, which the CSRF check compares against, is what Rack reports and so already follows `X-Forwarded-Host` and `X-Forwarded-Proto`; pass `origin: "https://app.example.com"` to pin it instead. `GET /cronwatch/api/check` with a bearer (the token or `CRON_SECRET`) runs the check, for an outside cron.
+Set `CRONWATCH_TOKEN` to a long random string and open `/cronwatch?token=<it>` once; the browser keeps a cookie. Without a token, while the environment (`Rails.env`, else `RAILS_ENV` or `RACK_ENV`) is `development` or `test`, it makes a token of its own and prints a sign-in link to standard output on its first request (open it once; unless `origin:` is set or the request's host is loopback, the link leaves the host out, since a client chooses it); anywhere else it answers 503. To rely on the app's own sign in, mount it behind that (Devise's `authenticate` block, or a routing constraint) and pass `token: nil`. The URLs, JSON shapes, headers and CSRF rules are the SDK's, so the MCP server reads it unchanged. The request's origin, which the CSRF check compares against, is what Rack reports and so already follows `X-Forwarded-Host` and `X-Forwarded-Proto`; pass `origin: "https://app.example.com"` to pin it instead. `GET /cronwatch/api/check` with a bearer (the token or `CRON_SECRET`) runs the check, for an outside cron.
 
 There is no `handler()` as in the TypeScript SDK: for a job triggered over HTTP, wrap the controller action's body in `CW.job(...).run` (declared once, at boot) and check the bearer in the controller.
 
@@ -225,7 +225,7 @@ Adds two to four sentences from Claude (likely cause, first thing to check) to e
 
 ## Sharing a database with a Node app
 
-The ActiveRecord store writes the same three tables as `@cronwatch/sdk/postgres` and `@cronwatch/sdk/sqlite`: same names, columns and indexes, epoch milliseconds in the time columns, the SDK's camelCase JSON in the JSON columns. [`test/active_record/node_compat_test.rb`](https://github.com/phillips-jon/cronwatch/blob/main/packages/ruby/test/active_record/node_compat_test.rb) runs the SDK's stores in Node beside this one, on SQLite and Postgres, and checks that each reads what the other wrote, that the tables are the same whoever creates them, and that the rows are the same bytes. Use the same prefix on both sides and give each job a name only one side uses. Then one dashboard, Rails or Node, shows every job, and one MCP server reads them all.
+The ActiveRecord store writes the same three tables as `@cronwatch/sdk/postgres` and `@cronwatch/sdk/sqlite`: same names, columns and indexes, epoch milliseconds in the time columns, the SDK's camelCase JSON in the JSON columns. [`test/active_record/node_compat_test.rb`](https://github.com/phillips-jon/cronwatch/blob/main/packages/ruby/test/active_record/node_compat_test.rb) runs the SDK's stores in Node beside this one, on SQLite and Postgres, and checks that each reads what the other wrote, that the tables are the same whoever creates them, and that the rows are the same bytes. Use the same prefix on both sides and give each job a name only one side uses. Then one dashboard, Rails or Node, shows every job, and one MCP server reads them all. The Python, PHP, Go and Rust ports keep the same tables too, so a process in any of them can share the database the same way.
 
 ## Kept in step with the TypeScript SDK
 

data/lib/cronwatch/alerts/provider.rb

@@ -93,13 +93,14 @@ module Cronwatch
         JS.head16(text, max)
       end
 
-      # The run fields worth attaching to a tracker event.
+      # The run fields worth attaching to a tracker event. A start before the
+      # year 1 or after 9999 is nil.
       def run_summary(alert)
         run = alert.run
         return nil unless run
 
         {
-          "id" => run.id, "status" => run.status.to_s, "startedAt" => JS.iso(run.started_at),
+          "id" => run.id, "status" => run.status.to_s, "startedAt" => Duration.iso_time(run.started_at),
           "durationMs" => run.duration_ms, "trigger" => run.trigger,
         }
       end

data/lib/cronwatch/client.rb

@@ -229,7 +229,7 @@ module Cronwatch
 
       finished_at = now
       run.finished_at = finished_at
-      run.duration_ms = [0, finished_at - started_at].max
+      run.duration_ms = Evaluate.run_duration(started_at, finished_at)
       run.metrics = recorder.metrics
       returned = result.is_a?(String) ? Output.utf8(result) : nil
       run.output = recorder.output || (returned && Output.cap(returned))
@@ -687,7 +687,7 @@ module Cronwatch
           state, result = yield(current)
           break [current, result] if same_state?(state, current)
 
-          version = current.version || 0
+          version = Evaluate.state_version(current)
           following = state.dup
           following.version = version + 1
           break [following, result] if write_state(following, version)
@@ -938,7 +938,7 @@ module Cronwatch
       run = from.dup
       run.status = :running
       run.finished_at = finished_at
-      run.duration_ms = [0, finished_at - from.started_at].max
+      run.duration_ms = Evaluate.run_duration(from.started_at, finished_at)
       run.error = nil
       run.output = join_output(from.output, added)
       run.metrics = (from.metrics || {}).merge(recorder.metrics)
@@ -1063,7 +1063,7 @@ module Cronwatch
         timeout = Evaluate.timeout_ms(definition)
         run.status = :timeout
         run.finished_at = at
-        run.duration_ms = at - run.started_at
+        run.duration_ms = Evaluate.run_duration(run.started_at, at)
         run.error = "Still running after #{Duration.format(timeout)}; marked as timed out"
         # Only over a row still running: a finish that landed meanwhile wins.
         next unless write_run_if(run, [:running])

data/lib/cronwatch/duration.rb

@@ -83,5 +83,22 @@ module Cronwatch
       text = format(abs)
       diff.negative? ? "#{text} ago" : "in #{text}"
     end
+
+    # The first millisecond written as a date: 0001-01-01T00:00:00.000Z.
+    FIRST_DATE_MS = -62_135_596_800_000
+    # The last millisecond written as a date: 9999-12-31T23:59:59.999Z.
+    LAST_DATE_MS = 253_402_300_799_999
+
+    # "2026-01-05T09:30:00.000Z", or nil for a time before the year 1 or
+    # after 9999. A start read from another process's row, or a damaged one,
+    # can be any number; outside those years it is not written as a date.
+    def iso_time(at)
+      at >= FIRST_DATE_MS && at <= LAST_DATE_MS ? JS.iso(at) : nil
+    end
+
+    # The words that stand in for a time iso_time does not write.
+    def beyond_dates(at)
+      at > LAST_DATE_MS ? "after 9999-12-31 23:59:59 UTC" : "before 0001-01-01 00:00:00 UTC"
+    end
   end
 end

data/lib/cronwatch/evaluate.rb

@@ -18,8 +18,36 @@ module Cronwatch
     CheckEvaluation = Struct.new(:state, :alerts, :next_expected_at, :due_at, keyword_init: true)
     SlowThreshold = Struct.new(:threshold_ms, :basis, keyword_init: true)
 
+    # The longest duration written: the largest integer JavaScript holds
+    # exactly, which every port and store reads back unchanged.
+    MAX_DURATION_MS = 9_007_199_254_740_991
+
     module_function
 
+    # How long a run took, from `started_at` to `finished_at`: 0 when it
+    # started later, and never more than MAX_DURATION_MS. A foreign row's
+    # start near a 64-bit limit must not make a duration no store can write.
+    def run_duration(started_at, finished_at)
+      ms = finished_at - started_at
+      return 0 unless ms.is_a?(Numeric) && ms.positive?
+
+      ms = ms.to_i if ms.is_a?(Float) && ms.finite? && ms == ms.floor
+      [ms, MAX_DURATION_MS].min
+    end
+
+    # The version a stored state counts as for compare_and_set_state: its
+    # `version` when that is a whole number from 0 to MAX_DURATION_MS
+    # (2**53 - 1), else 0, as when it is absent. The SQL stores read it the
+    # same way, so a foreign row's 1.5, "x" or -1 is written over by the next
+    # update instead of refusing every compare-and-set of its job for good.
+    def state_version(state)
+      version = state&.version
+      return 0 unless version.is_a?(Integer) || (version.is_a?(Float) && version.finite? && version == version.floor)
+      return 0 unless version >= 0 && version <= MAX_DURATION_MS
+
+      version.to_i
+    end
+
     def empty_state(job)
       JobState.new(job: job, open: {}, consecutive_failures: 0, silenced_until: nil, last_alert_at: nil,
                    pending_recovery: [], undelivered: [])

data/lib/cronwatch/format.rb

@@ -9,7 +9,10 @@ module Cronwatch
     def at_time(at, now)
       return "never" if at.nil?
 
-      "#{JS.iso(at).tr("T", " ")[0, 19]} UTC (#{Duration.relative(at, now)})"
+      iso = Duration.iso_time(at)
+      return Duration.beyond_dates(at) if iso.nil?
+
+      "#{iso.tr("T", " ")[0, 19]} UTC (#{Duration.relative(at, now)})"
     end
 
     def first_lines(text, n)

data/lib/cronwatch/pg_cron.rb

@@ -161,7 +161,7 @@ module Cronwatch
         finish = done ? [started_at, finished_at || started_at].max : nil
         Run.new(
           id: "#{id_prefix}#{row["runid"]}", job: job, status: status, started_at: started_at, finished_at: finish,
-          duration_ms: finish.nil? ? nil : finish - started_at,
+          duration_ms: finish.nil? ? nil : Evaluate.run_duration(started_at, finish),
           error: status == :failed ? (message || "pg_cron reported the run as failed") : nil,
           output: status == :ok ? message : nil, metrics: {}, trigger: "pg_cron",
         )

data/lib/cronwatch/schedule.rb

@@ -15,6 +15,15 @@ module Cronwatch
     # How early a run may start and still count for the fire it was meant for.
     EARLY_SLACK_MS = 60_000
 
+    # Four hundred Gregorian years: 146,097 days, a whole number of weeks,
+    # after which the calendar repeats date for date and weekday for weekday.
+    CYCLE_MS = 146_097 * 86_400_000
+    # The years the walker searches in, as croner does: a time before 400 is
+    # asked a cycle or more later (croner misreads a year below 100), and one
+    # from 2800 a cycle or more earlier (croner finds no fire past 3000).
+    WALK_FIRST_MS = -49_544_438_400_000 # 0400-01-01T00:00:00Z
+    WALK_LAST_MS = 26_192_246_400_000 # 2800-01-01T00:00:00Z
+
     Parsed = Struct.new(:kind, :source, :timezone, :every_ms, keyword_init: true) do
       include Serializable
 
@@ -80,12 +89,15 @@ module Cronwatch
     def fire_after(parsed, from)
       raise ArgumentError, "schedule \"#{parsed.source}\" was not made by Schedule.parse" unless parsed.pattern
 
-      probe = from
+      start = count_from(from)
+      return nil if start.nil?
+
+      probe = start
       4.times do
         runs = next_runs(parsed, 8, probe)
         return nil if runs.empty?
 
-        found = runs.find { |t| t > from }
+        found = runs.find { |t| t > start }
         return found if found
 
         probe += 3_600_000
@@ -101,8 +113,11 @@ module Cronwatch
       raise ArgumentError, "schedule \"#{parsed.source}\" was not made by Schedule.parse" unless parsed.pattern
 
       out = []
-      probe = from
-      last = from
+      start = count_from(from)
+      return out if start.nil?
+
+      probe = start
+      last = start
       1000.times do
         batch = next_runs(parsed, [limit + 1 - out.length, 24].min, probe)
         return out if batch.empty?
@@ -121,15 +136,39 @@ module Cronwatch
       out
     end
 
-    # Up to `count` fires, each found from the one before, as croner's nextRuns.
+    # A stored time as a cron's fires are counted from it. A start read from
+    # a foreign or damaged row can be any number: one before the year 1
+    # counts from just before its first millisecond, so the first fire of the
+    # year 1 is the next one, and one at or after the last millisecond of 9999
+    # has no fire after it at all (nil). Ported from countFrom in schedule.ts.
+    def count_from(from)
+      return nil if from >= Duration::LAST_DATE_MS
+
+      from >= Duration::FIRST_DATE_MS ? from : Duration::FIRST_DATE_MS - 1
+    end
+
+    # Up to `count` fires, each found from the one before, as croner's
+    # nextRuns, and none after 9999. A time outside the years the walker
+    # searches is moved by whole 400-year cycles into them, and its fires
+    # moved back, as runsAfter in schedule.ts asks croner: a time before 400
+    # goes forward, into the same local mean time every zone kept then, and
+    # one from 2800 goes back, to where the zone's present rules already hold.
     def next_runs(parsed, count, from)
+      from = count_from(from)
+      return [] if from.nil?
+
+      shift =
+        if from < WALK_FIRST_MS then -((from - WALK_FIRST_MS).div(CYCLE_MS)) * CYCLE_MS
+        elsif from >= WALK_LAST_MS then -((from - WALK_LAST_MS).div(CYCLE_MS) + 1) * CYCLE_MS
+        else 0
+        end
       runs = []
-      at = from
+      at = from + shift
       count.times do
         at = parsed.pattern.next_after(at, parsed.timezone)
-        break if at.nil?
+        break if at.nil? || at - shift > Duration::LAST_DATE_MS
 
-        runs << at
+        runs << (at - shift)
       end
       runs
     end
@@ -159,7 +198,9 @@ module Cronwatch
       due_at.nil? ? nil : Expectation.new(due_at: due_at, deadline: due_at + grace_ms)
     end
 
-    # The first fire that a run starting at `started_at` does not cover.
+    # The first fire that a run starting at `started_at` does not cover. A
+    # start before the year 1 covers none of them, so the first fire of the
+    # year 1 is due; after 9999 there is none (see count_from).
     def due_after_run(parsed, started_at)
       # A fire at or before the start is covered by the run itself.
       following_fire = fire_after(parsed, started_at)
@@ -189,6 +230,9 @@ module Cronwatch
     # ran early by up to an hour.
     def in_spring_forward_gap?(parsed, started_at, fire_at)
       lookback = 3 * 3_600_000
+      # Every zone kept its local mean time, with no clock change, in the year 1.
+      return false if fire_at - lookback < Duration::FIRST_DATE_MS
+
       after = utc_offset(fire_at, parsed.timezone)
       before = utc_offset(fire_at - lookback, parsed.timezone)
       gap = after - before

data/lib/cronwatch/stores/active_record.rb

@@ -344,8 +344,20 @@ module Cronwatch
         seq = pg ? "seq" : "rowid"
         # Byte order on both, so names sort the same whatever the database's collation.
         by_name = pg ? 'name COLLATE "C"' : "name"
-        # The version inside a state's JSON, 0 when it has none.
-        version = ->(column) { pg ? "COALESCE((#{column}->>'version')::bigint, 0)" : "COALESCE(json_extract(#{column}, '$.version'), 0)" }
+        # The version inside a state's JSON, as Evaluate.state_version reads
+        # it: a whole number from 0 to 2**53 - 1, else 0 (none, or a foreign
+        # row's 1.5 or "x", which must neither fail the statement nor refuse
+        # every write for good). Each CASE tests the JSON type before any cast.
+        version = lambda do |column|
+          if pg
+            v = "(#{column}->>'version')::numeric"
+            next "CASE WHEN jsonb_typeof(#{column}->'version') <> 'number' THEN 0 " \
+                 "WHEN #{v} % 1 = 0 AND #{v} BETWEEN 0 AND 9007199254740991 THEN #{v}::bigint ELSE 0 END"
+          end
+          v = "json_extract(#{column}, '$.version')"
+          "CASE WHEN json_type(#{column}, '$.version') NOT IN ('integer', 'real') THEN 0 " \
+            "WHEN #{v} = CAST(#{v} AS INTEGER) AND #{v} BETWEEN 0 AND 9007199254740991 THEN CAST(#{v} AS INTEGER) ELSE 0 END"
+        end
         sql = {
           upsert_job: "INSERT INTO #{p}jobs (name, definition, created_at, updated_at) VALUES (?, ?, ?, ?)\n      " \
                       "ON CONFLICT (name) DO UPDATE SET definition = excluded.definition, updated_at = excluded.updated_at",

data/lib/cronwatch/stores/memory.rb

@@ -134,7 +134,7 @@ module Cronwatch
       # wrote. See JobState#version.
       def compare_and_set_state(state, expected_version)
         sync do
-          next false unless (@states[state.job]&.version || 0) == expected_version
+          next false unless Evaluate.state_version(@states[state.job]) == expected_version
 
           @states[state.job] = clone(state, JobState)
           true

data/lib/cronwatch/triage/anthropic.rb

@@ -92,6 +92,11 @@ module Cronwatch
         "<job_data>\n#{text.gsub(TAG, "<_job_data")}\n</job_data>"
       end
 
+      # "2026-01-05T09:30:00.000Z", or the words for a time before the year 1 or after 9999.
+      def self.stamp(at)
+        Duration.iso_time(at) || Duration.beyond_dates(at)
+      end
+
       # The prompt: the alert, the definition, the triggering run and up to five earlier ones.
       def self.describe(triage_context)
         alert = triage_context.alert
@@ -104,7 +109,7 @@ module Cronwatch
         lines << "Job definition: #{JS.json(definition.respond_to?(:to_h) ? definition.to_h : definition)}"
         if run
           lines << ""
-          lines << "Triggering run: status #{run.status}, started #{JS.iso(run.started_at)}, duration #{duration(run)}, trigger #{run.trigger}"
+          lines << "Triggering run: status #{run.status}, started #{stamp(run.started_at)}, duration #{duration(run)}, trigger #{run.trigger}"
           lines << "Metrics: #{JS.json(run.metrics)}" if run.metrics && !run.metrics.empty?
           lines << "Error:\n#{data(JS.head16(run.error, 3000))}" if present?(run.error)
           lines << "Output (tail):\n#{data(JS.tail16(run.output, 3000))}" if present?(run.output)
@@ -116,7 +121,7 @@ module Cronwatch
           earlier.each do |r|
             error = present?(r.error) ? ", error: #{data(JS.head16(r.error.split("\n", -1).first.to_s, 160))}" : ""
             metrics = r.metrics && !r.metrics.empty? ? ", metrics #{JS.json(r.metrics)}" : ""
-            lines << "- #{r.status}, #{JS.iso(r.started_at)}, #{duration(r)}#{error}#{metrics}"
+            lines << "- #{r.status}, #{stamp(r.started_at)}, #{duration(r)}#{error}#{metrics}"
           end
         end
         lines.join("\n")

data/lib/cronwatch/version.rb

@@ -2,5 +2,5 @@
 
 module Cronwatch
   # Kept in step with @cronwatch/sdk.
-  VERSION = "0.7.0"
+  VERSION = "0.8.0"
 end

data/lib/cronwatch/web/html.rb

@@ -329,7 +329,9 @@ module Cronwatch
       def stamp(at, now)
         return %(<span class="muted">never</span>) if at.nil?
 
-        iso = JS.iso(at.to_i)
+        iso = Duration.iso_time(at.to_i)
+        return %(<span class="nowrap">#{Duration.beyond_dates(at.to_i)}</span>) if iso.nil?
+
         %(<time class="nowrap" datetime="#{iso}" title="#{iso.sub("T", " ")[0, 19]} UTC">#{h(Duration.relative(at, now))}</time>)
       end
 

data/lib/cronwatch/web/timeline.rb

@@ -86,12 +86,19 @@ module Cronwatch
         "#{WEEKDAYS[d.wday]} #{d.day} #{MONTHS[d.month - 1]}"
       end
 
-      # "22:42" on the same UTC day as `now`, otherwise "25 Sep 22:42".
+      # "22:42" on the same UTC day as `now`, otherwise "25 Sep 22:42", and
+      # "1 Jan 0001 02:00" in another UTC year. A time before the year 1 or
+      # after 9999 (a start read from a foreign or damaged row) is "before 1
+      # Jan 0001 00:00" or "after 31 Dec 9999 23:59".
       def when_at(t, now)
+        return "after 31 Dec 9999 23:59" if t > Duration::LAST_DATE_MS
+        return "before 1 Jan 0001 00:00" if t < Duration::FIRST_DATE_MS
+
         return clock(t) if t.div(DAY) == now.div(DAY)
 
         d = utc(t)
-        "#{d.day} #{MONTHS[d.month - 1]} #{clock(t)}"
+        year = d.year == utc(now).year ? "" : Kernel.format(" %04d", d.year)
+        "#{d.day} #{MONTHS[d.month - 1]}#{year} #{clock(t)}"
       end
 
       # The job's schedule, parsed, or nil when it has none or it no longer parses.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cronwatch
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Jon C. Phillips