feat(timezone): add timezone-aware session context (#671)

* feat(timezone): add timezone-aware session context (#661)

All timestamps were UTC-only, causing daily logs to split at UTC midnight,
cron schedules to fire in UTC, and no quiet hours for heartbeat. This adds
timezone as a per-session property flowing from the client.

Key changes:
- New `src/timezone.rs` module with resolution chain, parsing, and detection
- `IncomingMessage` carries optional timezone from client
- `JobContext.user_timezone` flows timezone to tools
- `next_cron_fire()` accepts timezone for schedule evaluation
- `Trigger::Cron` stores optional timezone (backward-compatible)
- Workspace gains `_tz` variants for daily logs and system prompt
- Heartbeat supports quiet hours (`HEARTBEAT_QUIET_START/END`)
- Web frontend sends `Intl.DateTimeFormat().resolvedOptions().timeZone`
- REPL auto-detects system timezone
- `DEFAULT_TIMEZONE` env var / settings for server-wide default

Storage stays UTC. Conversion happens at display boundaries.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* fix(timezone): address review feedback on timezone-aware sessions

- Validate quiet hours values (0-23) in HeartbeatConfig::resolve()
- Fall back to settings values when env vars are unset for quiet hours
- Validate IANA timezone strings in routine_create/update with parse_timezone
- Add timezone field to routine_create tool schema
- Allow standalone timezone update on cron routines without changing schedule
- Return path from append_daily_log_tz to avoid TOCTOU race at midnight
- Delegate append_daily_log to append_daily_log_tz(entry, UTC) to avoid drift
- Preserve timezone through approval flow via PendingApproval.user_timezone
- Improve test_today_in_tz to not depend on hardcoded year
- Add 3 regression tests for quiet hours config validation

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* style: fix formatting in routine.rs

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* fix(timezone): address second round of review feedback

- Remove .claude/scheduled_tasks.lock from repo and add to .gitignore
- Store resolved timezone (not raw message.timezone) in PendingApproval
- Carry forward user_timezone through chained approvals in thread_ops
- Wire quiet_hours_start/end from config to HeartbeatRunner
- Support X-Timezone header as fallback in chat_send_handler

[skip-regression-check]

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* fix(timezone): include user's local time in time tool response

The time tool's "now" operation now returns local_iso and timezone
fields based on ctx.user_timezone, so the LLM can report time in
the user's timezone instead of always UTC.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* style: fix formatting in time.rs

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* fix(timezone): address Copilot review round 3 — validation, deterministic tests, schema fixes

- Validate DEFAULT_TIMEZONE and HEARTBEAT_TIMEZONE at config load time
- Add timezone field to HeartbeatSettings and config::HeartbeatConfig
- Wire heartbeat timezone from config through agent_loop to HeartbeatRunner
- Add timezone to routine_update tool schema (was accepted but not advertised)
- Error on schedule/timezone update for non-cron routines
- Validate timezone in Trigger::from_db (coerce invalid to None with warning)
- Validate timezone in approval path (thread_ops.rs) before overwriting
- Time tool always includes timezone/local_iso fields (fallback to UTC)
- Make quiet hours tests deterministic using current UTC hour
- Add regression tests for config validation

[skip-regression-check]

Co-Authored-By: Claude Opus 4.6 <[email protected]>

---------

Co-authored-by: Claude Opus 4.6 <[email protected]>

src/agent/routine.rs

@@ -57,7 +57,11 @@ pub struct Routine {
 #[serde(tag = "type", rename_all = "snake_case")]
 pub enum Trigger {
     /// Fire on a cron schedule (e.g. "0 9 * * MON-FRI" or "every 2h").
-    Cron { schedule: String },
+    Cron {
+        schedule: String,
+        #[serde(default)]
+        timezone: Option<String>,
+    },
     /// Fire when a channel message matches a pattern.
     Event {
         /// Optional channel filter (e.g. "telegram", "slack").
@@ -99,7 +103,21 @@ impl Trigger {
                         field: "schedule".into(),
                     })?
                     .to_string();
-                Ok(Trigger::Cron { schedule })
+                let timezone = config
+                    .get("timezone")
+                    .and_then(|v| v.as_str())
+                    .and_then(|tz| {
+                        if crate::timezone::parse_timezone(tz).is_some() {
+                            Some(tz.to_string())
+                        } else {
+                            tracing::warn!(
+                                "Ignoring invalid timezone '{}' from DB for cron trigger",
+                                tz
+                            );
+                            None
+                        }
+                    });
+                Ok(Trigger::Cron { schedule, timezone })
             }
             "event" => {
                 let pattern = config
@@ -137,7 +155,10 @@ impl Trigger {
     /// Serialize trigger-specific config to JSON for DB storage.
     pub fn to_config_json(&self) -> serde_json::Value {
         match self {
-            Trigger::Cron { schedule } => serde_json::json!({ "schedule": schedule }),
+            Trigger::Cron { schedule, timezone } => serde_json::json!({
+                "schedule": schedule,
+                "timezone": timezone,
+            }),
             Trigger::Event { channel, pattern } => serde_json::json!({
                 "pattern": pattern,
                 "channel": channel,
@@ -415,12 +436,25 @@ pub fn content_hash(content: &str) -> u64 {
 }
 
 /// Parse a cron expression and compute the next fire time from now.
-pub fn next_cron_fire(schedule: &str) -> Result<Option<DateTime<Utc>>, RoutineError> {
+///
+/// When `timezone` is provided and valid, the schedule is evaluated in that
+/// timezone and the result is converted back to UTC. Otherwise UTC is used.
+pub fn next_cron_fire(
+    schedule: &str,
+    timezone: Option<&str>,
+) -> Result<Option<DateTime<Utc>>, RoutineError> {
     let cron_schedule =
         cron::Schedule::from_str(schedule).map_err(|e| RoutineError::InvalidCron {
             reason: e.to_string(),
         })?;
-    Ok(cron_schedule.upcoming(Utc).next())
+    if let Some(tz) = timezone.and_then(crate::timezone::parse_timezone) {
+        Ok(cron_schedule
+            .upcoming(tz)
+            .next()
+            .map(|dt| dt.with_timezone(&Utc)))
+    } else {
+        Ok(cron_schedule.upcoming(Utc).next())
+    }
 }
 
 #[cfg(test)]
@@ -433,10 +467,11 @@ mod tests {
     fn test_trigger_roundtrip() {
         let trigger = Trigger::Cron {
             schedule: "0 9 * * MON-FRI".to_string(),
+            timezone: None,
         };
         let json = trigger.to_config_json();
         let parsed = Trigger::from_db("cron", json).expect("parse cron");
-        assert!(matches!(parsed, Trigger::Cron { schedule } if schedule == "0 9 * * MON-FRI"));
+        assert!(matches!(parsed, Trigger::Cron { schedule, .. } if schedule == "0 9 * * MON-FRI"));
     }
 
     #[test]
@@ -509,16 +544,58 @@ mod tests {
     #[test]
     fn test_next_cron_fire_valid() {
         // Every minute should always have a next fire
-        let next = next_cron_fire("* * * * * *").expect("valid cron");
+        let next = next_cron_fire("* * * * * *", None).expect("valid cron");
         assert!(next.is_some());
     }
 
     #[test]
     fn test_next_cron_fire_invalid() {
-        let result = next_cron_fire("not a cron");
+        let result = next_cron_fire("not a cron", None);
         assert!(result.is_err());
     }
 
+    #[test]
+    fn test_trigger_cron_timezone_roundtrip() {
+        let trigger = Trigger::Cron {
+            schedule: "0 9 * * MON-FRI".to_string(),
+            timezone: Some("America/New_York".to_string()),
+        };
+        let json = trigger.to_config_json();
+        let parsed = Trigger::from_db("cron", json).expect("parse cron");
+        assert!(matches!(parsed, Trigger::Cron { schedule, timezone }
+                if schedule == "0 9 * * MON-FRI"
+                && timezone.as_deref() == Some("America/New_York")));
+    }
+
+    #[test]
+    fn test_trigger_cron_no_timezone_backward_compat() {
+        let json = serde_json::json!({"schedule": "0 9 * * *"});
+        let parsed = Trigger::from_db("cron", json).expect("parse cron");
+        assert!(matches!(parsed, Trigger::Cron { timezone, .. } if timezone.is_none()));
+    }
+
+    #[test]
+    fn test_trigger_cron_invalid_timezone_coerced_to_none() {
+        let json = serde_json::json!({"schedule": "0 9 * * *", "timezone": "Fake/Zone"});
+        let parsed = Trigger::from_db("cron", json).expect("parse cron");
+        assert!(
+            matches!(parsed, Trigger::Cron { timezone, .. } if timezone.is_none()),
+            "invalid timezone should be coerced to None"
+        );
+    }
+
+    #[test]
+    fn test_next_cron_fire_with_timezone() {
+        let next_utc = next_cron_fire("0 0 9 * * * *", None)
+            .expect("valid cron")
+            .expect("has next");
+        let next_est = next_cron_fire("0 0 9 * * * *", Some("America/New_York"))
+            .expect("valid cron")
+            .expect("has next");
+        // EST is UTC-5 (or EDT UTC-4), so the UTC result should differ
+        assert_ne!(next_utc, next_est, "timezone should shift the fire time");
+    }
+
     #[test]
     fn test_guardrails_default() {
         let g = RoutineGuardrails::default();
@@ -531,7 +608,8 @@ mod tests {
     fn test_trigger_type_tag() {
         assert_eq!(
             Trigger::Cron {
-                schedule: String::new()
+                schedule: String::new(),
+                timezone: None,
             }
             .type_tag(),
             "cron"