feat(schedule_type): minute-precision windows + variable maintenance length

Lifts the two hard restrictions in PR #18:
  * window bounds were `int hour` (0-23) → now `int minutes-since-UTC-midnight` (0-1439)
  * maintenance window was exactly 1 hour → now any duration in [1, 180] minutes
    ((maint_to - maint_from) mod 1440)

## Schema migration (additive)

`_migrate_schema()` detects legacy "hours" rows (any row where MAX of the
6 window columns is ≤ 23) and multiplies each column by 60 to convert
to minutes. Idempotent — post-conversion values are well above 23 so
the guard never fires twice.

## Touched surfaces

- `models/schedule_type.py` — column comments updated; new
  `compute_maintenance_duration()` helper (returns 1-1440 min, treats
  from==to as 1440 which is then rejected by validator)
- `schemas/schedule_type.py` — `*_from`/`*_to` upper bound 23 → 1440;
  `_validate_maintenance_window` accepts 1-180min duration; response
  includes derived `maintenance_duration_minutes`
- `schemas/schedule_type_special_slot.py` — `minute_in_window` max
  59→179; `estimated_duration` max 60→180
- `routers/schedule_type.py` — PATCH re-validates merged maintenance
  pair (partial updates can put the row into an invalid combo the
  pydantic single-field validator can't catch); `_attach_derived`
  populates the new response field
- `routers/schedule_type_special_slot.py` — `_validate_fits_window`
  now takes the parent's maintenance duration instead of hard-coded 60
- `routers/calendar.py` — `_scheduled_inside_window` arg renamed
  hour→min; the maintenance-window guard error message formats
  HH:MM not HH:00
- `services/special_slot_materialiser.py` — materialised
  `scheduled_at` derived from `(maint_from_min + tpl.minute_in_window)`
  with hour/minute split

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

app/api/routers/calendar.py

@@ -205,12 +205,14 @@ def create_slot(
             st.maintenance_from,
             st.maintenance_to,
         ):
+            mf_h, mf_m = divmod(st.maintenance_from, 60)
+            mt_h, mt_m = divmod(st.maintenance_to, 60)
             raise HTTPException(
                 status_code=422,
                 detail=(
                     f"slot at {payload.scheduled_at} duration {payload.estimated_duration}min "
                     f"intersects the maintenance window "
-                    f"{st.maintenance_from:02d}:00-{st.maintenance_to:02d}:00 UTC of "
+                    f"{mf_h:02d}:{mf_m:02d}-{mt_h:02d}:{mt_m:02d} UTC of "
                     f"schedule_type '{st.name}' — that window is admin-reserved"
                 ),
             )
@@ -341,22 +343,21 @@ def _require_agent(db: Session, agent_id: str, claw_identifier: str) -> Agent:
 def _scheduled_inside_window(
     scheduled_at,
     estimated_duration_minutes: int,
-    window_from_hour: int,
-    window_to_hour: int,
+    window_from_min: int,
+    window_to_min: int,
 ) -> bool:
-    """True if [scheduled_at, scheduled_at+duration] intersects [from:00, to:00].
+    """True if [scheduled_at, scheduled_at+duration] intersects [from, to).
 
-    Handles the 23→0 wrap case (window straddles UTC midnight).
+    Window bounds are minutes-since-UTC-midnight (0-1439). Handles the
+    case where the window crosses UTC midnight (e.g. 23:30→01:00).
     """
     start_min = scheduled_at.hour * 60 + scheduled_at.minute
     end_min = start_min + max(estimated_duration_minutes, 1)
-    win_start_min = window_from_hour * 60
-    win_end_min = window_to_hour * 60
-    if win_end_min > win_start_min:
+    if window_to_min > window_from_min:
         # normal same-day window
-        return start_min < win_end_min and end_min > win_start_min
-    # wrap-around: window = [from..24:00) ∪ [00:00..to)
-    return (start_min < 24 * 60 and end_min > win_start_min) or end_min > win_end_min
+        return start_min < window_to_min and end_min > window_from_min
+    # wrap-around: window = [from..1440) ∪ [0..to)
+    return (start_min < 1440 and end_min > window_from_min) or end_min > window_to_min
 
 
 # Admin-locked special slots accept only these agent-driven status

app/api/routers/schedule_type.py

@@ -57,6 +57,18 @@ def _require_schedule_manage(db: Session, user: User) -> User:
     return user
 
 
+def _attach_derived(st: ScheduleType) -> ScheduleType:
+    """Attach derived fields (maintenance_duration_minutes) so the
+    pydantic ScheduleTypeResponse picks them up via from_attributes.
+
+    Pydantic with from_attributes reads attributes off the ORM object;
+    setting a transient attr here avoids having to convert through dict.
+    """
+    if st is not None:
+        st.maintenance_duration_minutes = st.compute_maintenance_duration()
+    return st
+
+
 # ---------------------------------------------------------------------------
 # Schedule Type CRUD
 # ---------------------------------------------------------------------------
@@ -71,7 +83,7 @@ def list_schedule_types(
     current_user: User = Depends(get_current_user_or_apikey),
 ):
     _require_schedule_read(db, current_user)
-    return db.query(ScheduleType).all()
+    return [_attach_derived(st) for st in db.query(ScheduleType).all()]
 
 
 @router.post(
@@ -96,11 +108,13 @@ def create_schedule_type(
         work_to=payload.work_to,
         entertainment_from=payload.entertainment_from,
         entertainment_to=payload.entertainment_to,
+        maintenance_from=payload.maintenance_from,
+        maintenance_to=payload.maintenance_to,
     )
     db.add(st)
     db.commit()
     db.refresh(st)
-    return st
+    return _attach_derived(st)
 
 
 @router.patch(
@@ -120,12 +134,23 @@ def update_schedule_type(
     if not st:
         raise HTTPException(404, "Schedule type not found")
 
-    for field, value in payload.model_dump(exclude_unset=True).items():
+    update_fields = payload.model_dump(exclude_unset=True)
+    for field, value in update_fields.items():
         setattr(st, field, value)
 
+    # Re-validate maintenance after merge (partial updates can put the row
+    # into an invalid window combo that the pydantic schema couldn't catch
+    # because it only saw one field).
+    from app.schemas.schedule_type import _validate_maintenance_window
+    try:
+        _validate_maintenance_window(st.maintenance_from, st.maintenance_to)
+    except ValueError as e:
+        db.rollback()
+        raise HTTPException(422, str(e))
+
     db.commit()
     db.refresh(st)
-    return st
+    return _attach_derived(st)
 
 
 @router.delete(
@@ -181,7 +206,8 @@ def get_my_schedule_type(
     if not agent.schedule_type_id:
         return None
 
-    return db.query(ScheduleType).filter(ScheduleType.id == agent.schedule_type_id).first()
+    st = db.query(ScheduleType).filter(ScheduleType.id == agent.schedule_type_id).first()
+    return _attach_derived(st) if st else None
 
 
 @router.put(

app/api/routers/schedule_type_special_slot.py

@@ -75,15 +75,17 @@ def _fetch_schedule_type(db: Session, schedule_type_id: int) -> ScheduleType:
 def _validate_fits_window(
     minute_in_window: int,
     estimated_duration: int,
+    maintenance_duration_minutes: int,
 ) -> None:
-    """Reject special slots that wouldn't fit inside the 1-hour window."""
-    if minute_in_window + estimated_duration > 60:
+    """Reject special slots that wouldn't fit inside the parent's maintenance window."""
+    if minute_in_window + estimated_duration > maintenance_duration_minutes:
         raise HTTPException(
             422,
             (
                 f"special slot does not fit in maintenance window: "
                 f"minute_in_window={minute_in_window} + "
-                f"estimated_duration={estimated_duration} > 60"
+                f"estimated_duration={estimated_duration} > "
+                f"maintenance window {maintenance_duration_minutes}min"
             ),
         )
 
@@ -127,8 +129,8 @@ def create_special_slot(
     current_user: User = Depends(get_current_user_or_apikey),
 ):
     _require_schedule_manage(db, current_user)
-    _fetch_schedule_type(db, schedule_type_id)
-    _validate_fits_window(payload.minute_in_window, payload.estimated_duration)
+    st = _fetch_schedule_type(db, schedule_type_id)
+    _validate_fits_window(payload.minute_in_window, payload.estimated_duration, st.compute_maintenance_duration())
 
     dup = (
         db.query(ScheduleTypeSpecialSlot)
@@ -188,7 +190,8 @@ def update_special_slot(
     update_fields = payload.model_dump(exclude_unset=True)
     next_min = update_fields.get("minute_in_window", slot.minute_in_window)
     next_dur = update_fields.get("estimated_duration", slot.estimated_duration)
-    _validate_fits_window(next_min, next_dur)
+    parent = _fetch_schedule_type(db, schedule_type_id)
+    _validate_fits_window(next_min, next_dur, parent.compute_maintenance_duration())
 
     for field, value in update_fields.items():
         setattr(slot, field, value)