macroclaw 0.34.0 → 0.36.0

package/src/{prompts.ts → prompt-builder.ts}

@@ -1,4 +1,6 @@
-export const SYSTEM_PROMPT = `\
+import { DateTime } from "luxon";
+
+const SYSTEM_PROMPT_BASE = `\
 AI assistant running in macroclaw, an autonomous agent platform. \
 Persistent workspace at cwd with config, memory, skills. \
 Refer to workspace CLAUDE.md for identity, personality, conventions.
@@ -16,6 +18,7 @@ Architecture: message bridge connecting chat interface and scheduled tasks. \
 Persistent session — conversation history carries across messages. Workspace persists across sessions.
 
 Event format: every incoming message is wrapped in an <event> XML block. Attributes:
+- time — local time when the event was created (ISO 8601, minute precision).
 - name — short identifier for this event (e.g. "check-logs", "cron-daily").
 - type — what triggered this event. One of:
   - user-message — direct user message. Content in <text>, optional <files>.
@@ -65,12 +68,6 @@ Use "silent" when check finds nothing new, "send" when noteworthy.
 MessageButtons: include a buttons field (flat array of label strings) to attach inline buttons below your message. \
 Each button gets its own row. Max 27 characters per label — if options need more detail, describe them in the message and use short labels on buttons.`;
 
-// --- Event builder ---
-
-function escapeXml(text: string): string {
-  return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
-}
-
 interface BuildXmlFields {
   text?: string;
   files?: string[];
@@ -84,101 +81,120 @@ interface BuildXmlFields {
   result?: { text: string; files?: string[] };
 }
 
-function buildXml(name: string, type: string, session: string, fields: BuildXmlFields): string {
-  const lines: string[] = [
-    `<event name="${escapeXml(name)}" type="${type}" session="${session}">`,
-  ];
+export class PromptBuilder {
+  readonly #timezone: string;
 
-  if (fields.backgroundedEvent) {
-    lines.push(`<backgrounded-event name="${escapeXml(fields.backgroundedEvent)}" />`);
+  constructor(timezone: string) {
+    this.#timezone = timezone;
   }
 
-  if (fields.schedule) {
-    const attrs = [`name="${escapeXml(fields.schedule.name)}"`];
-    if (fields.schedule.missedBy) attrs.push(`missed-by="${escapeXml(fields.schedule.missedBy)}"`);
-    if (fields.schedule.scheduledAt) attrs.push(`scheduled-at="${escapeXml(fields.schedule.scheduledAt)}"`);
-    lines.push(`<schedule ${attrs.join(" ")} />`);
+  get systemPrompt(): string {
+    return `${SYSTEM_PROMPT_BASE}\n\nTimezone: ${this.#timezone}. TZ env var is set — \`date\` and other CLI tools return local time.`;
   }
 
-  if (fields.originalEvent) {
-    lines.push(`<original-event name="${escapeXml(fields.originalEvent)}" />`);
+  #localTime(): string {
+    return DateTime.now().setZone(this.#timezone).toFormat("yyyy-MM-dd'T'HH:mm");
   }
 
-  if (fields.targetEvent) {
-    lines.push(`<target-event name="${escapeXml(fields.targetEvent)}" />`);
+  static #escapeXml(text: string): string {
+    return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
   }
 
-  if (fields.progress) {
-    lines.push(`<progress>${escapeXml(fields.progress)}</progress>`);
-  }
+  static #buildXml(name: string, type: string, session: string, time: string, fields: BuildXmlFields): string {
+    const esc = PromptBuilder.#escapeXml;
+    const lines: string[] = [
+      `<event time="${time}" name="${esc(name)}" type="${type}" session="${session}">`,
+    ];
+
+    if (fields.backgroundedEvent) {
+      lines.push(`<backgrounded-event name="${esc(fields.backgroundedEvent)}" />`);
+    }
+
+    if (fields.schedule) {
+      const attrs = [`name="${esc(fields.schedule.name)}"`];
+      if (fields.schedule.missedBy) attrs.push(`missed-by="${esc(fields.schedule.missedBy)}"`);
+      if (fields.schedule.scheduledAt) attrs.push(`scheduled-at="${esc(fields.schedule.scheduledAt)}"`);
+      lines.push(`<schedule ${attrs.join(" ")} />`);
+    }
+
+    if (fields.originalEvent) {
+      lines.push(`<original-event name="${esc(fields.originalEvent)}" />`);
+    }
+
+    if (fields.targetEvent) {
+      lines.push(`<target-event name="${esc(fields.targetEvent)}" />`);
+    }
+
+    if (fields.progress) {
+      lines.push(`<progress>${esc(fields.progress)}</progress>`);
+    }
+
+    if (fields.result) {
+      lines.push("<result>");
+      lines.push(`<text>${esc(fields.result.text)}</text>`);
+      if (fields.result.files?.length) {
+        lines.push("<files>");
+        for (const f of fields.result.files) {
+          lines.push(`  <file path="${esc(f)}" />`);
+        }
+        lines.push("</files>");
+      }
+      lines.push("</result>");
+    }
+
+    if (fields.button) {
+      lines.push(`<button>${esc(fields.button)}</button>`);
+    }
+
+    if (fields.text) {
+      lines.push(`<text>${esc(fields.text)}</text>`);
+    }
 
-  if (fields.result) {
-    lines.push("<result>");
-    lines.push(`<text>${escapeXml(fields.result.text)}</text>`);
-    if (fields.result.files?.length) {
+    if (fields.files?.length) {
       lines.push("<files>");
-      for (const f of fields.result.files) {
-        lines.push(`  <file path="${escapeXml(f)}" />`);
+      for (const f of fields.files) {
+        lines.push(`  <file path="${esc(f)}" />`);
       }
       lines.push("</files>");
     }
-    lines.push("</result>");
-  }
 
-  if (fields.button) {
-    lines.push(`<button>${escapeXml(fields.button)}</button>`);
-  }
+    if (fields.instructions) {
+      lines.push(`<instructions>${esc(fields.instructions)}</instructions>`);
+    }
 
-  if (fields.text) {
-    lines.push(`<text>${escapeXml(fields.text)}</text>`);
+    lines.push("</event>");
+    return lines.join("\n");
   }
 
-  if (fields.files?.length) {
-    lines.push("<files>");
-    for (const f of fields.files) {
-      lines.push(`  <file path="${escapeXml(f)}" />`);
-    }
-    lines.push("</files>");
+  userMessage(name: string, text: string, opts?: { files?: string[]; backgroundedEvent?: string }): string {
+    return PromptBuilder.#buildXml(name, "user-message", "main", this.#localTime(), { text, files: opts?.files, backgroundedEvent: opts?.backgroundedEvent });
   }
 
-  if (fields.instructions) {
-    lines.push(`<instructions>${escapeXml(fields.instructions)}</instructions>`);
+  buttonClick(name: string, button: string, opts?: { backgroundedEvent?: string }): string {
+    return PromptBuilder.#buildXml(name, "button-click", "main", this.#localTime(), { button, backgroundedEvent: opts?.backgroundedEvent });
   }
 
-  lines.push("</event>");
-  return lines.join("\n");
-}
-
-// --- Per-type event builders ---
-
-export function userMessageEvent(name: string, text: string, opts?: { files?: string[]; backgroundedEvent?: string }): string {
-  return buildXml(name, "user-message", "main", { text, files: opts?.files, backgroundedEvent: opts?.backgroundedEvent });
-}
-
-export function buttonClickEvent(name: string, button: string, opts?: { backgroundedEvent?: string }): string {
-  return buildXml(name, "button-click", "main", { button, backgroundedEvent: opts?.backgroundedEvent });
-}
-
-export function scheduleTriggerEvent(name: string, schedule: { name: string; missedBy?: string; scheduledAt?: string }, text: string): string {
-  return buildXml(name, "schedule-trigger", "background", { schedule, text });
-}
+  scheduleTrigger(name: string, schedule: { name: string; missedBy?: string; scheduledAt?: string }, text: string): string {
+    return PromptBuilder.#buildXml(name, "schedule-trigger", "background", this.#localTime(), { schedule, text });
+  }
 
-export function backgroundAgentStartEvent(name: string, text: string): string {
-  return buildXml(name, "background-agent-start", "background", { text });
-}
+  backgroundAgentStart(name: string, text: string): string {
+    return PromptBuilder.#buildXml(name, "background-agent-start", "background", this.#localTime(), { text });
+  }
 
-export function backgroundAgentResultEvent(name: string, originalEvent: string, result: { text: string; files?: string[] }, instructions: string, opts?: { backgroundedEvent?: string }): string {
-  return buildXml(name, "background-agent-result", "main", { originalEvent, result, instructions, backgroundedEvent: opts?.backgroundedEvent });
-}
+  backgroundAgentResult(name: string, originalEvent: string, result: { text: string; files?: string[] }, instructions: string, opts?: { backgroundedEvent?: string }): string {
+    return PromptBuilder.#buildXml(name, "background-agent-result", "main", this.#localTime(), { originalEvent, result, instructions, backgroundedEvent: opts?.backgroundedEvent });
+  }
 
-export function backgroundAgentProgressEvent(name: string, originalEvent: string, progress: string, instructions: string, opts?: { backgroundedEvent?: string }): string {
-  return buildXml(name, "background-agent-progress", "main", { originalEvent, progress, instructions, backgroundedEvent: opts?.backgroundedEvent });
-}
+  backgroundAgentProgress(name: string, originalEvent: string, progress: string, instructions: string, opts?: { backgroundedEvent?: string }): string {
+    return PromptBuilder.#buildXml(name, "background-agent-progress", "main", this.#localTime(), { originalEvent, progress, instructions, backgroundedEvent: opts?.backgroundedEvent });
+  }
 
-export function peekEvent(name: string, targetEvent: string, instructions: string): string {
-  return buildXml(name, "peek", "background", { targetEvent, instructions });
-}
+  peek(name: string, targetEvent: string, instructions: string): string {
+    return PromptBuilder.#buildXml(name, "peek", "background", this.#localTime(), { targetEvent, instructions });
+  }
 
-export function healthCheckEvent(name: string, targetEvent: string, instructions: string): string {
-  return buildXml(name, "health-check", "background", { targetEvent, instructions });
+  healthCheck(name: string, targetEvent: string, instructions: string): string {
+    return PromptBuilder.#buildXml(name, "health-check", "background", this.#localTime(), { targetEvent, instructions });
+  }
 }

package/src/scheduler.test.ts

@@ -73,7 +73,7 @@ describe("Scheduler — cron jobs", () => {
 		});
 
 		const onJob = makeOnJob();
-		const s = new Scheduler(TEST_DIR, { onJob });
+		const s = new Scheduler(TEST_DIR, { timezone: "UTC", onJob });
 		s.start();
 		s.stop();
 
@@ -86,7 +86,7 @@ describe("Scheduler — cron jobs", () => {
 		});
 
 		const onJob = makeOnJob();
-		const s = new Scheduler(TEST_DIR, { onJob });
+		const s = new Scheduler(TEST_DIR, { timezone: "UTC", onJob });
 		s.start();
 		s.stop();
 
@@ -102,7 +102,7 @@ describe("Scheduler — cron jobs", () => {
 		});
 
 		const onJob = makeOnJob();
-		const s = new Scheduler(TEST_DIR, { onJob });
+		const s = new Scheduler(TEST_DIR, { timezone: "UTC", onJob });
 		s.start();
 		s.stop();
 
@@ -119,7 +119,7 @@ describe("Scheduler — cron jobs", () => {
 		});
 
 		const onJob = makeOnJob();
-		const s = new Scheduler(TEST_DIR, { onJob });
+		const s = new Scheduler(TEST_DIR, { timezone: "UTC", onJob });
 		s.start();
 		s.stop();
 
@@ -134,7 +134,7 @@ describe("Scheduler — cron jobs", () => {
 		});
 
 		const onJob = makeOnJob();
-		const s = new Scheduler(TEST_DIR, { onJob });
+		const s = new Scheduler(TEST_DIR, { timezone: "UTC", onJob });
 		s.start();
 		s.stop();
 
@@ -147,7 +147,7 @@ describe("Scheduler — cron jobs", () => {
 		});
 
 		const onJob = makeOnJob();
-		const s = new Scheduler(TEST_DIR, { onJob });
+		const s = new Scheduler(TEST_DIR, { timezone: "UTC", onJob });
 		s.start();
 		s.stop();
 
@@ -164,7 +164,7 @@ describe("Scheduler — fireAt jobs", () => {
 		});
 
 		const onJob = makeOnJob();
-		const s = new Scheduler(TEST_DIR, { onJob });
+		const s = new Scheduler(TEST_DIR, { timezone: "UTC", onJob });
 		s.start();
 		s.stop();
 
@@ -181,7 +181,7 @@ describe("Scheduler — fireAt jobs", () => {
 		});
 
 		const onJob = makeOnJob();
-		const s = new Scheduler(TEST_DIR, { onJob });
+		const s = new Scheduler(TEST_DIR, { timezone: "UTC", onJob });
 		s.start();
 		s.stop();
 
@@ -197,7 +197,7 @@ describe("Scheduler — fireAt jobs", () => {
 		});
 
 		const onJob = makeOnJob();
-		const s = new Scheduler(TEST_DIR, { onJob });
+		const s = new Scheduler(TEST_DIR, { timezone: "UTC", onJob });
 		s.start();
 		s.stop();
 
@@ -214,7 +214,7 @@ describe("Scheduler — fireAt jobs", () => {
 		});
 
 		const onJob = makeOnJob();
-		const s = new Scheduler(TEST_DIR, { onJob });
+		const s = new Scheduler(TEST_DIR, { timezone: "UTC", onJob });
 		s.start();
 		s.stop();
 
@@ -236,7 +236,7 @@ describe("Scheduler — fireAt jobs", () => {
 		});
 
 		const onJob = makeOnJob();
-		const s = new Scheduler(TEST_DIR, { onJob });
+		const s = new Scheduler(TEST_DIR, { timezone: "UTC", onJob });
 		s.start();
 		s.stop();
 
@@ -252,7 +252,7 @@ describe("Scheduler — fireAt jobs", () => {
 		});
 
 		const onJob = makeOnJob();
-		const s = new Scheduler(TEST_DIR, { onJob });
+		const s = new Scheduler(TEST_DIR, { timezone: "UTC", onJob });
 		s.start();
 		s.stop();
 
@@ -273,7 +273,7 @@ describe("Scheduler — fireAt jobs", () => {
 		});
 
 		const onJob = makeOnJob();
-		const s = new Scheduler(TEST_DIR, { onJob });
+		const s = new Scheduler(TEST_DIR, { timezone: "UTC", onJob });
 		s.start();
 		s.stop();
 
@@ -290,13 +290,49 @@ describe("Scheduler — fireAt jobs", () => {
 		});
 
 		const onJob = makeOnJob();
-		const s = new Scheduler(TEST_DIR, { onJob });
+		const s = new Scheduler(TEST_DIR, { timezone: "UTC", onJob });
 		s.start();
 		s.stop();
 
 		expect(onJob).toHaveBeenCalledWith("smart", "think", "opus");
 	});
 
+	it("interprets offset-less fireAt in the configured timezone", () => {
+		// Create a fireAt 30 seconds ago in Europe/Prague local time (no offset)
+		const now = new Date();
+		const pragueStr = now.toLocaleString("en-US", { timeZone: "Europe/Prague" });
+		const utcStr = now.toLocaleString("en-US", { timeZone: "UTC" });
+		const pragueOffsetMs = new Date(pragueStr).getTime() - new Date(utcStr).getTime();
+		// Wall-clock time in Prague 30 seconds ago
+		const pragueNow = new Date(now.getTime() + pragueOffsetMs - 30_000);
+		const naive = pragueNow.toISOString().replace("Z", "").replace(/\.\d+$/, "");
+
+		writeScheduleConfig({
+			jobs: [{ name: "local", fireAt: naive, prompt: "local time" }],
+		});
+
+		const onJob = makeOnJob();
+		const s = new Scheduler(TEST_DIR, { timezone: "Europe/Prague", onJob });
+		s.start();
+		s.stop();
+
+		expect(onJob).toHaveBeenCalledWith("local", "local time", undefined);
+	});
+
+	it("preserves explicit offset in fireAt (ignores configured timezone)", () => {
+		// fireAt with explicit +00:00 offset, 30s ago — should fire regardless of configured tz
+		writeScheduleConfig({
+			jobs: [{ name: "explicit", fireAt: justNowFireAt(), prompt: "with offset" }],
+		});
+
+		const onJob = makeOnJob();
+		const s = new Scheduler(TEST_DIR, { timezone: "Asia/Tokyo", onJob });
+		s.start();
+		s.stop();
+
+		expect(onJob).toHaveBeenCalledWith("explicit", "with offset", undefined);
+	});
+
 	it("still fires when write-back of schedule.json fails", () => {
 		writeScheduleConfig({
 			jobs: [{ name: "once", fireAt: justNowFireAt(), prompt: "fire" }],
@@ -306,7 +342,7 @@ describe("Scheduler — fireAt jobs", () => {
 		chmodSync(SCHEDULE_FILE, 0o444);
 
 		const onJob = makeOnJob();
-		const s = new Scheduler(TEST_DIR, { onJob });
+		const s = new Scheduler(TEST_DIR, { timezone: "UTC", onJob });
 		s.start();
 		s.stop();
 
@@ -321,7 +357,7 @@ describe("Scheduler — validation and edge cases", () => {
 		rmSync(SCHEDULE_FILE, { force: true });
 
 		const onJob = makeOnJob();
-		const s = new Scheduler(TEST_DIR, { onJob });
+		const s = new Scheduler(TEST_DIR, { timezone: "UTC", onJob });
 		s.start();
 		s.stop();
 
@@ -332,7 +368,7 @@ describe("Scheduler — validation and edge cases", () => {
 		writeFileSync(SCHEDULE_FILE, "not json{{{");
 
 		const onJob = makeOnJob();
-		const s = new Scheduler(TEST_DIR, { onJob });
+		const s = new Scheduler(TEST_DIR, { timezone: "UTC", onJob });
 		s.start();
 		s.stop();
 
@@ -343,7 +379,7 @@ describe("Scheduler — validation and edge cases", () => {
 		writeScheduleConfig({ jobs: "not-array" });
 
 		const onJob = makeOnJob();
-		const s = new Scheduler(TEST_DIR, { onJob });
+		const s = new Scheduler(TEST_DIR, { timezone: "UTC", onJob });
 		s.start();
 		s.stop();
 
@@ -356,7 +392,7 @@ describe("Scheduler — validation and edge cases", () => {
 		});
 
 		const onJob = makeOnJob();
-		const s = new Scheduler(TEST_DIR, { onJob });
+		const s = new Scheduler(TEST_DIR, { timezone: "UTC", onJob });
 		s.start();
 		s.stop();
 
@@ -369,7 +405,7 @@ describe("Scheduler — validation and edge cases", () => {
 		});
 
 		const onJob = makeOnJob();
-		const s = new Scheduler(TEST_DIR, { onJob });
+		const s = new Scheduler(TEST_DIR, { timezone: "UTC", onJob });
 		s.start();
 		s.stop();
 
@@ -384,7 +420,7 @@ describe("Scheduler — validation and edge cases", () => {
 		writeScheduleConfig({ jobs: [] });
 
 		const onJob = makeOnJob();
-		const s = new Scheduler(TEST_DIR, { onJob });
+		const s = new Scheduler(TEST_DIR, { timezone: "UTC", onJob });
 		s.start();
 		s.stop(); // should not throw
 	});
@@ -395,7 +431,7 @@ describe("Scheduler — validation and edge cases", () => {
 		});
 
 		const onJob = makeOnJob();
-		const s = new Scheduler(TEST_DIR, { onJob });
+		const s = new Scheduler(TEST_DIR, { timezone: "UTC", onJob });
 		s.start();
 		s.stop();
 
@@ -403,7 +439,7 @@ describe("Scheduler — validation and edge cases", () => {
 
 		// Start again with a new instance — the lastMinute tracker is per-instance
 		const onJob2 = makeOnJob();
-		const s2 = new Scheduler(TEST_DIR, { onJob: onJob2 });
+		const s2 = new Scheduler(TEST_DIR, { timezone: "UTC", onJob: onJob2 });
 		s2.start();
 		s2.stop();
 
@@ -416,7 +452,7 @@ describe("Scheduler — validation and edge cases", () => {
 		});
 
 		const onJob = makeOnJob();
-		const s = new Scheduler(TEST_DIR, { onJob });
+		const s = new Scheduler(TEST_DIR, { timezone: "UTC", onJob });
 		s.start();
 		s.stop();
 

package/src/scheduler.ts

@@ -1,6 +1,7 @@
 import { readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { CronExpressionParser } from "cron-parser";
+import { DateTime } from "luxon";
 import { z } from "zod/v4";
 import { createLogger } from "./logger";
 
@@ -27,6 +28,7 @@ export interface MissedInfo {
 }
 
 export interface SchedulerConfig {
+	timezone: string;
 	onJob: (name: string, prompt: string, model?: string, missed?: MissedInfo) => void;
 }
 
@@ -37,11 +39,13 @@ export class Scheduler {
 	#lastMinute = -1;
 	#schedulePath: string;
 	#config: SchedulerConfig;
+	#timezone: string;
 	#timer: Timer | null = null;
 
 	constructor(workspace: string, config: SchedulerConfig) {
 		this.#schedulePath = join(workspace, "data", "schedule.json");
 		this.#config = config;
+		this.#timezone = config.timezone;
 	}
 
 	start(): void {
@@ -116,7 +120,7 @@ export class Scheduler {
 
 	#evaluateCronJob(job: { name: string; cron: string; prompt: string; model?: string }, now: Date): void {
 		try {
-			const interval = CronExpressionParser.parse(job.cron);
+			const interval = CronExpressionParser.parse(job.cron, { tz: this.#timezone });
 			const prev = interval.prev();
 			const diff = Math.abs(now.getTime() - prev.getTime());
 			if (diff < 60_000) {
@@ -128,11 +132,22 @@ export class Scheduler {
 		}
 	}
 
+	/** Parse a fireAt string, interpreting offset-less timestamps in the given timezone. */
+	static #parseFireAt(fireAt: string, timezone: string): Date {
+		const probe = DateTime.fromISO(fireAt, { setZone: true });
+		if (probe.isValid && probe.isOffsetFixed) {
+			// Has explicit offset (Z, +HH:MM, etc.) — use as-is
+			return probe.toJSDate();
+		}
+		// No offset — interpret as local time in the configured timezone
+		return DateTime.fromISO(fireAt, { zone: timezone }).toJSDate();
+	}
+
 	#evaluateFireAtJob(
 		job: { name: string; fireAt: string; prompt: string; model?: string },
 		now: Date,
 	): "remove" | "keep" {
-		const fireAt = new Date(job.fireAt);
+		const fireAt = Scheduler.#parseFireAt(job.fireAt, this.#timezone);
 		if (Number.isNaN(fireAt.getTime())) {
 			log.warn({ name: job.name, fireAt: job.fireAt }, "Invalid fireAt date");
 			return "keep";

package/src/settings.test.ts

@@ -10,6 +10,7 @@ const validSettings: Settings = {
   chatId: "12345678",
   model: "sonnet",
   workspace: "~/.macroclaw-workspace",
+  timezone: "UTC",
   logLevel: "debug",
 };
 
@@ -39,10 +40,36 @@ describe("SettingsManager.load", () => {
       chatId: "12345678",
       model: "sonnet",
       workspace: "~/.macroclaw-workspace",
+      timezone: "UTC",
       logLevel: "info",
     });
   });
 
+  it("trims string settings loaded from file", () => {
+    mkdirSync(tmpDir, { recursive: true });
+    writeFileSync(join(tmpDir, "settings.json"), JSON.stringify({
+      botToken: "  123:ABC  ",
+      chatId: " 12345678 ",
+      model: " opus ",
+      workspace: "  /custom/workspace  ",
+      timezone: "  Europe/Prague  ",
+      openaiApiKey: "  sk-test  ",
+      logLevel: " warn ",
+      pinoramaUrl: "  http://localhost:6200  ",
+    }));
+    const settings = new SettingsManager(tmpDir).load();
+    expect(settings).toEqual({
+      botToken: "123:ABC",
+      chatId: "12345678",
+      model: "opus",
+      workspace: "/custom/workspace",
+      timezone: "Europe/Prague",
+      openaiApiKey: "sk-test",
+      logLevel: "warn",
+      pinoramaUrl: "http://localhost:6200",
+    });
+  });
+
   it("applies defaults for optional fields", () => {
     mkdirSync(tmpDir, { recursive: true });
     writeFileSync(join(tmpDir, "settings.json"), JSON.stringify({
@@ -60,6 +87,7 @@ describe("SettingsManager.load", () => {
       chatId: "123",
       model: "opus",
       workspace: "/custom",
+      timezone: "UTC",
       openaiApiKey: "sk-test",
       logLevel: "info",
       pinoramaUrl: "http://localhost:6200",
@@ -123,6 +151,28 @@ describe("SettingsManager.load", () => {
     expect(mockExit).toHaveBeenCalledWith(1);
     process.exit = origExit;
   });
+
+  it("exits with code 1 when validation fails (invalid timezone)", () => {
+    mkdirSync(tmpDir, { recursive: true });
+    writeFileSync(join(tmpDir, "settings.json"), JSON.stringify({
+      botToken: "tok",
+      chatId: "123",
+      timezone: "Europe/Prgaaue",
+    }));
+
+    const mockExit = mock(() => { throw new Error("exit"); });
+    const origExit = process.exit;
+    process.exit = mockExit as any;
+
+    try {
+      new SettingsManager(tmpDir).load();
+    } catch {
+      // expected
+    }
+
+    expect(mockExit).toHaveBeenCalledWith(1);
+    process.exit = origExit;
+  });
 });
 
 describe("SettingsManager.save", () => {
@@ -169,7 +219,7 @@ describe("SettingsManager.loadRaw", () => {
 describe("SettingsManager.applyEnvOverrides", () => {
   const envVars = [
     "TELEGRAM_BOT_TOKEN", "AUTHORIZED_CHAT_ID", "MODEL",
-    "WORKSPACE", "OPENAI_API_KEY", "LOG_LEVEL", "PINORAMA_URL",
+    "WORKSPACE", "TIMEZONE", "OPENAI_API_KEY", "LOG_LEVEL", "PINORAMA_URL",
   ];
   const savedEnv: Record<string, string | undefined> = {};
 
@@ -223,6 +273,37 @@ describe("SettingsManager.applyEnvOverrides", () => {
     expect(overrides.has("logLevel")).toBe(true);
     expect(overrides.has("pinoramaUrl")).toBe(true);
   });
+
+  it("trims env override values before returning settings", () => {
+    process.env.MODEL = " opus ";
+    process.env.WORKSPACE = " /override/path ";
+    process.env.TIMEZONE = " Europe/Prague ";
+    process.env.LOG_LEVEL = " error ";
+    process.env.PINORAMA_URL = " http://override:6200 ";
+    const { settings } = new SettingsManager(tmpDir).applyEnvOverrides(validSettings);
+    expect(settings.model).toBe("opus");
+    expect(settings.workspace).toBe("/override/path");
+    expect(settings.timezone).toBe("Europe/Prague");
+    expect(settings.logLevel).toBe("error");
+    expect(settings.pinoramaUrl).toBe("http://override:6200");
+  });
+
+  it("exits with code 1 when an env override is invalid", () => {
+    process.env.TIMEZONE = "Europe/Prgaaue";
+
+    const mockExit = mock(() => { throw new Error("exit"); });
+    const origExit = process.exit;
+    process.exit = mockExit as any;
+
+    try {
+      new SettingsManager(tmpDir).applyEnvOverrides(validSettings);
+    } catch {
+      // expected
+    }
+
+    expect(mockExit).toHaveBeenCalledWith(1);
+    process.exit = origExit;
+  });
 });
 
 describe("SettingsManager.print", () => {