feat: per-chatter timezone for prompts and cron scheduling

The system prompt's date line and cron schedules were rendered/evaluated
in the server's timezone (UTC on hosted pods), so a SOUL.md instruction
like "use 东八区" reliably lost to the clock value, and "每天早上 9 点"
reminders fired at 下午 5 点 Beijing time.

Timezone is a property of the chatter, not the agent — different-timezone
users of the same agent each get their own wall clock:

- scope: new prefs namespace with chatter-first resolution
  (chatter,agent) → (chatter) → (agent) → (system); SaveUserTimezone
  writes at user scope so the preference follows the chatter across agents
- set_timezone tool: persists the chatter's IANA timezone where the
  runtime reads it (also exposed in chatbot mode); a USER.md note alone
  never affected scheduling
- system prompt: date line rendered in the chatter's local timezone via
  ContextBuilder.tzResolver — the model never does offset arithmetic
- cron: jobs freeze the chatter's timezone at creation (was hardcoded
  "UTC"); zone-less 'once' datetimes parse in it; recurrences evaluate in
  it via NextOccurrenceIn. cron-type jobs no longer fire once immediately
  on creation — first run is the actual next occurrence
- heartbeat: timestamps in the agent-default timezone
- deploy: TZ=Asia/Shanghai server-default fallback in compose/k8s/helm

Legacy rows keep their "UTC" semantics; empty timezone = server-local.

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

Author: idoubi

deploy/docker/docker-compose.yml

@@ -26,6 +26,11 @@ services:
     volumes:
       - fastclaw-data:/data/.fastclaw
     environment:
+      # Server default timezone (IANA name). This is the LAST fallback in
+      # the chain chatter pref → agent default → system default → TZ —
+      # without it the container runs UTC and agents whose chatters never
+      # set a timezone get UTC wall clocks and UTC-fired schedules.
+      TZ: "${TZ:-Asia/Shanghai}"
       # FASTCLAW_HOME — sqlite db path + sandbox root + skill cache live here
       FASTCLAW_HOME: /data/.fastclaw
       # Bind to all interfaces so the host port mapping works

deploy/helm/fastclaw/templates/configmap.yaml

@@ -9,6 +9,11 @@ data:
   FASTCLAW_BIND: "all"
   FASTCLAW_STORAGE_TYPE: "postgres"
   FASTCLAW_STORAGE_AUTO_MIGRATE: "true"
+  {{- with .Values.timezone }}
+  ## Server default timezone — last fallback after chatter / agent /
+  ## system prefs.
+  TZ: {{ . | quote }}
+  {{- end }}
 
   ## Object store
   FASTCLAW_OBJECT_STORE_TYPE: {{ .Values.objectStore.type | quote }}

deploy/helm/fastclaw/values.yaml

@@ -12,6 +12,12 @@ image:
   # imagePullSecrets:
   #   - name: regcred
 
+## Server default timezone (IANA name) — the LAST fallback in the chain
+## chatter pref → agent default → system default → TZ. Empty = container
+## default (UTC): agents whose chatters never set a timezone then see UTC
+## wall clocks and get UTC-fired schedules.
+timezone: "Asia/Shanghai"
+
 ## Gateway
 gateway:
   replicas: 2

deploy/k8s/fastclaw.yaml

@@ -78,6 +78,12 @@ data:
   FASTCLAW_STORAGE_TYPE: "postgres"
   FASTCLAW_STORAGE_AUTO_MIGRATE: "true"
 
+  # Server default timezone (IANA name) — the LAST fallback in the chain
+  # chatter pref → agent default → system default → TZ. Without it pods
+  # run UTC, so agents whose chatters never set a timezone see UTC wall
+  # clocks and get UTC-fired schedules.
+  TZ: "Asia/Shanghai"
+
   # ─── Provider 1: Aliyun OSS (default example) ───
   FASTCLAW_OBJECT_STORE_TYPE: "aliyun-oss"
   FASTCLAW_OBJECT_STORE_REGION: "cn-hangzhou"

deploy/multi-pod/docker-compose.yaml

@@ -79,6 +79,9 @@ services:
       dockerfile: Dockerfile
     environment:
       # Same config on both pods — that's the whole point of "stateless".
+      # TZ included so cross-pod runs exercise the server-default
+      # timezone fallback the same way single-pod deploys do.
+      TZ: Asia/Shanghai
       FASTCLAW_STORAGE_TYPE: postgres
       FASTCLAW_STORAGE_DSN: postgres://fastclaw:fastclaw@db:5432/fastclaw?sslmode=disable
       FASTCLAW_MODE: cloud
@@ -104,6 +107,7 @@ services:
       context: ../..
       dockerfile: Dockerfile
     environment:
+      TZ: Asia/Shanghai
       FASTCLAW_STORAGE_TYPE: postgres
       FASTCLAW_STORAGE_DSN: postgres://fastclaw:fastclaw@db:5432/fastclaw?sslmode=disable
       FASTCLAW_MODE: cloud

internal/agent/context.go

@@ -189,6 +189,12 @@ type ContextBuilder struct {
 	store   MemoryStore
 	userID  string
 	agentID string
+	// tzResolver maps a chatterUID to their effective *time.Location
+	// (chatter pref → agent default → system default, resolved through
+	// scope prefs). Wired by the manager when a relational store is
+	// available; nil (or a nil return) falls back to server-local time,
+	// which preserves the legacy single-tenant behavior.
+	tzResolver func(chatterUID string) *time.Location
 }
 
 // ctx returns a context tagged with this builder's user, used when reading
@@ -233,6 +239,26 @@ func (cb *ContextBuilder) SetDisplayName(n string) { cb.displayName = n }
 
 // resolvedPromptMode returns the active mode with empty/unknown values
 // normalized to PromptModeAgent so callers can switch on the result.
+// SetTimezoneResolver wires the chatterUID → *time.Location lookup used
+// to render the prompt's date line (and runtime context) in the
+// chatter's local time. Re-apply after rebuilding the ContextBuilder
+// (ReloadWorkspaceFiles), like the other Set* state.
+func (cb *ContextBuilder) SetTimezoneResolver(f func(chatterUID string) *time.Location) {
+	cb.tzResolver = f
+}
+
+// chatterLocation resolves the timezone to render times in for a given
+// chatter. Falls back to server-local when no resolver is wired or it
+// has nothing for this chatter.
+func (cb *ContextBuilder) chatterLocation(chatterUID string) *time.Location {
+	if cb.tzResolver != nil {
+		if loc := cb.tzResolver(chatterUID); loc != nil {
+			return loc
+		}
+	}
+	return time.Local
+}
+
 func (cb *ContextBuilder) resolvedPromptMode() string {
 	switch cb.promptMode {
 	case config.PromptModeChatbot, config.PromptModeCustomize:
@@ -285,9 +311,17 @@ func (cb *ContextBuilder) BuildSystemPromptAs(chatterUID string, chatterMem *Mem
 	// which then often runs in parallel with a web_search whose
 	// query was built from the model's stale year. Putting now() in
 	// the prompt removes the dependency at the root.
-	now := time.Now()
+	//
+	// Rendered in the CHATTER's timezone (tzResolver), not the
+	// server's: a hosted pod runs UTC while the person typing is in
+	// 东八区, and a SOUL.md instruction to "use UTC+8" reliably loses
+	// to a clock value labeled "Use this". Pre-converting here means
+	// the model never does timezone arithmetic — different chatters of
+	// the same agent each see their own wall clock.
+	loc := cb.chatterLocation(chatterUID)
+	now := time.Now().In(loc)
 	wd := now.Weekday().String()
-	dateLine := fmt.Sprintf("Current date/time: %s (%s, %s). Use this — do NOT call `date` to learn what day it is.",
+	dateLine := fmt.Sprintf("Current date/time: %s (%s, %s — the chatter's local timezone). Use this — do NOT call `date` to learn what day it is.",
 		now.Format("2006-01-02 15:04:05 -0700"), wd, now.Location().String())
 
 	switch mode {
@@ -357,7 +391,9 @@ MEMORY.md — pick the right file):
 - Chatter tells you their **name** / nickname / what to call them → ` + bt + `USER.md` + bt + `
 - Chatter tells you their **role / job / background** → ` + bt + `USER.md` + bt + `
 - Chatter tells you their **preferences** (language, tone, style) → ` + bt + `USER.md` + bt + `
-- Chatter tells you their **location / timezone** → ` + bt + `USER.md` + bt + `
+- Chatter tells you their **location / timezone** → call ` + bt + `set_timezone` + bt + `
+  (if available — it switches your clock and their scheduled tasks to
+  their local time; a USER.md note alone does NOT), then note it in ` + bt + `USER.md` + bt + ` too
 - A decision you made together that matters next time → ` + bt + `MEMORY.md` + bt + `
 - A recurring topic / ongoing project / shared context → ` + bt + `MEMORY.md` + bt + `
 - Chatter explicitly says "remember that X" (not about who they are) → ` + bt + `MEMORY.md` + bt + `
@@ -840,7 +876,9 @@ You have the ability to update workspace files to maintain knowledge over time:
 Use the write_file tool to update these files when appropriate. Keep entries concise and useful.
 
 # Scheduling Time-Bound Tasks
-When the user asks you to do something at a specific moment, after a delay, or on a recurring schedule (e.g. "5 分钟后提醒我", "每天 9 点", "every Monday morning"), call the create_cron_job tool. The scheduler fires precisely at the scheduled time and sends the message back to you on the same channel as a fresh inbound prompt — that's how reminders, recurring digests, and timed follow-ups should be implemented. NEVER write timed reminders into HEARTBEAT.md: that file is reviewed only on a coarse heartbeat tick and is wrong for any short-fuse or precise-timing request.`)
+When the user asks you to do something at a specific moment, after a delay, or on a recurring schedule (e.g. "5 分钟后提醒我", "每天 9 点", "every Monday morning"), call the create_cron_job tool. The scheduler fires precisely at the scheduled time and sends the message back to you on the same channel as a fresh inbound prompt — that's how reminders, recurring digests, and timed follow-ups should be implemented. NEVER write timed reminders into HEARTBEAT.md: that file is reviewed only on a coarse heartbeat tick and is wrong for any short-fuse or precise-timing request.
+
+Schedules are interpreted in the CHATTER'S local timezone — the same one your "Current date/time" line above is rendered in. Write "每天 9 点" as '0 9 * * *' directly; do NOT convert to UTC. If the chatter mentions being in a different timezone or city, call set_timezone first so both your clock and their schedules follow it.`)
 	}
 
 	return strings.Join(parts, "\n\n---\n\n")

internal/agent/heartbeat.go

@@ -68,10 +68,14 @@ func (hb *Heartbeat) tick(ctx context.Context) {
 	// 1. Check HEARTBEAT.md for tasks
 	tasks := hb.loadHeartbeatTasks()
 	if tasks != "" {
-		now := time.Now()
+		// Agent-default timezone (chatterUID="" → agent/system prefs,
+		// else server local): heartbeat has no chatter, but HEARTBEAT.md
+		// conditions are written in the operator's wall clock, not the
+		// pod's (UTC on hosted deployments).
+		now := time.Now().In(hb.agent.chatterLocation(""))
 		heartbeatMsg := fmt.Sprintf(
 			"[Heartbeat — %s]\nCurrent tasks from HEARTBEAT.md:\n%s\n\nReview these tasks and take action on any that need attention based on the current date/time.",
-			now.Format("2006-01-02 15:04:05"),
+			now.Format("2006-01-02 15:04:05 -0700"),
 			tasks,
 		)
 

internal/agent/loop.go

@@ -21,6 +21,7 @@ import (
 	"github.com/fastclaw-ai/fastclaw/internal/privacy"
 	"github.com/fastclaw-ai/fastclaw/internal/provider"
 	"github.com/fastclaw-ai/fastclaw/internal/sandbox"
+	"github.com/fastclaw-ai/fastclaw/internal/scope"
 	"github.com/fastclaw-ai/fastclaw/internal/session"
 	"github.com/fastclaw-ai/fastclaw/internal/store"
 	"github.com/fastclaw-ai/fastclaw/internal/toolproviders"
@@ -2989,6 +2990,9 @@ var chatbotBuiltinAllowlist = []string{
 	"tts",
 	"write_file",
 	"edit_file",
+	// set_timezone keeps "their local time" right for chat (greetings,
+	// "晚安" timing) — chatbots need it as much as full agents do.
+	"set_timezone",
 }
 
 // builtinAllowForMode returns the built-in tool name allowlist for the
@@ -3011,6 +3015,21 @@ func (a *Agent) WorkspacePath() string {
 	return a.workspacePath
 }
 
+// chatterLocation resolves the effective timezone for a chatter via
+// scope prefs (chatter pref → agent default → system default). Server-
+// local when no relational store is wired or nothing is configured —
+// the legacy single-tenant behavior. Passed to the ContextBuilder as
+// the tzResolver so the system prompt's date line renders in the
+// chatter's wall clock; the cron tool runs the same resolution at
+// job-creation time.
+func (a *Agent) chatterLocation(chatterUID string) *time.Location {
+	if a.dataStore == nil {
+		return time.Local
+	}
+	tz := scope.Timezone(context.Background(), a.dataStore, chatterUID, a.agentID)
+	return scope.LoadLocationOrLocal(tz)
+}
+
 // UpdateConfig updates the agent's runtime config (model, temperature, etc.)
 func (a *Agent) UpdateConfig(rc config.ResolvedAgent) {
 	a.model = rc.Model
@@ -3135,6 +3154,12 @@ func (a *Agent) ReloadWorkspaceFiles() {
 		a.ctxBuilder.agentID = a.name
 		a.ctxBuilder.userID = a.ownerUserID
 	}
+	// Chatter-timezone date line — same re-apply rule as the Store
+	// wiring above: the rebuilt ContextBuilder starts with a nil
+	// resolver and would silently fall back to server-local time.
+	if a.dataStore != nil {
+		a.ctxBuilder.SetTimezoneResolver(a.chatterLocation)
+	}
 }
 
 // extractMediaPaths scans tool output for MEDIA: lines and returns file paths.

internal/agent/manager.go

@@ -222,6 +222,11 @@ func (m *Manager) buildAgent(rc config.ResolvedAgent, prov provider.Provider, mb
 		// at execute time (bindSession stamps them per-turn) so the
 		// fired message routes back to the originating chat.
 		tools.RegisterCronTools(ag.registry, m.opts.dataStore, m.uid, rc.ID)
+		// set_timezone persists the chatter's IANA timezone into scope
+		// prefs — the same rows the system-prompt date line and cron
+		// scheduling resolve through. Needs the relational store, so it
+		// rides the same guard as cron.
+		tools.RegisterTimezoneTool(ag.registry, m.opts.dataStore)
 		// /goal feature: token-accounting hook + update_goal tool, all
 		// keyed on the agent's owner (set above by SetOwnerUserID).
 		// Same dataStore guard as cron because both features need the
@@ -232,6 +237,10 @@ func (m *Manager) buildAgent(rc config.ResolvedAgent, prov provider.Provider, mb
 		// on an in-memory counter that restart-clears) can hit the
 		// store directly without re-plumbing through Manager.
 		ag.dataStore = m.opts.dataStore
+		// Date line in the chatter's timezone — needs dataStore for the
+		// scope-prefs lookup, hence wired here and re-applied by
+		// ReloadWorkspaceFiles after every ctxBuilder rebuild.
+		ag.ctxBuilder.SetTimezoneResolver(ag.chatterLocation)
 	}
 	// Stamp agentID even when no workspaceStore is wired (single-user
 	// local mode), so usage metering can record per-agent rollups.

internal/agent/tools/cron.go

@@ -9,6 +9,7 @@ import (
 	"time"
 
 	"github.com/fastclaw-ai/fastclaw/internal/cron"
+	"github.com/fastclaw-ai/fastclaw/internal/scope"
 	"github.com/fastclaw-ai/fastclaw/internal/store"
 )
 
@@ -42,7 +43,7 @@ func RegisterCronTools(r *Registry, st store.Store, userID, agentID string) {
 				},
 				"schedule": map[string]interface{}{
 					"type":        "string",
-					"description": "When to fire. For type='cron': a 5-field cron expression like '0 9 * * *'. For type='interval': a duration like '5m' / '30m' / '2h'. For type='once': an ISO-8601 datetime in UTC like '2026-05-02T15:56:52'.",
+					"description": "When to fire, in the CHATTER'S local timezone (the timezone shown on the 'Current date/time' line of your system prompt) — write '每天早上 9 点' as '0 9 * * *' directly, do NOT convert to UTC. For type='cron': a 5-field cron expression like '0 9 * * *'. For type='interval': a duration like '5m' / '30m' / '2h'. For type='once': an ISO-8601 datetime like '2026-05-02T15:56:52' (no offset = chatter's local time; an explicit offset like '+08:00' or 'Z' is honored as written).",
 				},
 				"message": map[string]interface{}{
 					"type":        "string",
@@ -104,6 +105,15 @@ func makeCreateCronJob(st store.Store, r *Registry, userID, agentID string) Tool
 		channel := r.MessageChannel()
 		chatID := r.MessageChatID()
 
+		// The chatter's effective timezone governs how the schedule is
+		// read: zone-less 'once' datetimes and cron wall-clock fields
+		// both mean "their local time" (the same zone the system
+		// prompt's date line is rendered in), not the server's. The
+		// resolved name is frozen onto the row so the scheduler keeps
+		// evaluating recurrences in it even if the chatter later moves.
+		tzName := scope.Timezone(ctx, st, r.ChatterUserID(), agentID)
+		loc := scope.LoadLocationOrLocal(tzName)
+
 		id := generateUUID()
 		now := time.Now()
 
@@ -113,9 +123,10 @@ func makeCreateCronJob(st store.Store, r *Registry, userID, agentID string) Tool
 		case "once":
 			t, err := time.Parse(time.RFC3339, args.Schedule)
 			if err != nil {
-				t, err = time.Parse("2006-01-02T15:04:05", args.Schedule)
+				// No explicit offset — interpret in the chatter's zone.
+				t, err = time.ParseInLocation("2006-01-02T15:04:05", args.Schedule, loc)
 				if err != nil {
-					return "", fmt.Errorf("once schedule must be ISO datetime (e.g. 2026-05-06T15:30:00Z), got: %q", args.Schedule)
+					return "", fmt.Errorf("once schedule must be ISO datetime (e.g. 2026-05-06T15:30:00), got: %q", args.Schedule)
 				}
 			}
 			if t.Before(now) {
@@ -130,8 +141,10 @@ func makeCreateCronJob(st store.Store, r *Registry, userID, agentID string) Tool
 			}
 			nextRun = now.Add(dur)
 		default:
-			// cron expression — fire on next scheduler tick
-			nextRun = now
+			// cron expression — first occurrence in the chatter's zone.
+			// (Previously nextRun=now, which fired the job once
+			// immediately on creation — a spurious reminder.)
+			nextRun = cron.NextOccurrenceIn(args.Schedule, now, loc)
 		}
 
 		job := &store.CronJobRecord{
@@ -143,7 +156,10 @@ func makeCreateCronJob(st store.Store, r *Registry, userID, agentID string) Tool
 			Message:   args.Message,
 			Channel:   channel,
 			ChatID:    chatID,
-			Timezone:  "UTC",
+			// "" = server-local; the scheduler's LocationOf maps it
+			// the same way LoadLocationOrLocal did above, so creation
+			// and recurrence agree.
+			Timezone:  tzName,
 			Enabled:   true,
 			NextRun:   &nextRun,
 			CreatedAt: now,
@@ -156,7 +172,15 @@ func makeCreateCronJob(st store.Store, r *Registry, userID, agentID string) Tool
 		// Wake the scheduler to pick up this new job
 		cron.NotifyJobCreated()
 
-		return fmt.Sprintf("Cron job created successfully.\nID: %s\nName: %s\nSchedule: %s\nType: %s", id, args.Name, args.Schedule, jobType), nil
+		// Echo the effective timezone + first fire so the model can
+		// confirm the local-time interpretation to the user ("好的，
+		// 北京时间每天 9 点") instead of guessing.
+		tzShown := tzName
+		if tzShown == "" {
+			tzShown = loc.String() + " (server default)"
+		}
+		return fmt.Sprintf("Cron job created successfully.\nID: %s\nName: %s\nSchedule: %s\nType: %s\nTimezone: %s\nFirst fire: %s",
+			id, args.Name, args.Schedule, jobType, tzShown, nextRun.In(loc).Format("2006-01-02 15:04:05 -0700")), nil
 	}
 }