macroclaw 0.45.0 → 0.47.0

package/src/scheduler.test.ts

@@ -17,7 +17,7 @@ function readScheduleConfig() {
 }
 
 function makeOnJob() {
-	return mock((_name: string, _prompt: string, _model?: string, _missed?: { missedBy: string; scheduledAt: string }) => {});
+	return mock((_name: string, _prompt: string, _model?: string, _missed?: { missedBy: string; scheduledAt: string }, _chat?: string) => {});
 }
 
 // Build a cron expression that matches the current minute
@@ -77,7 +77,7 @@ describe("Scheduler — cron jobs", () => {
 		s.start();
 		s.stop();
 
-		expect(onJob).toHaveBeenCalledWith("test-job", "do something", undefined);
+		expect(onJob).toHaveBeenCalledWith("test-job", "do something", undefined, undefined, undefined);
 	});
 
 	it("does not call onJob for non-matching jobs", () => {
@@ -107,7 +107,7 @@ describe("Scheduler — cron jobs", () => {
 		s.stop();
 
 		expect(onJob).toHaveBeenCalledTimes(1);
-		expect(onJob).toHaveBeenCalledWith("good", "good", undefined);
+		expect(onJob).toHaveBeenCalledWith("good", "good", undefined, undefined, undefined);
 	});
 
 	it("handles multiple matching jobs", () => {
@@ -124,8 +124,8 @@ describe("Scheduler — cron jobs", () => {
 		s.stop();
 
 		expect(onJob).toHaveBeenCalledTimes(2);
-		expect(onJob).toHaveBeenCalledWith("first", "first", undefined);
-		expect(onJob).toHaveBeenCalledWith("second", "second", undefined);
+		expect(onJob).toHaveBeenCalledWith("first", "first", undefined, undefined, undefined);
+		expect(onJob).toHaveBeenCalledWith("second", "second", undefined, undefined, undefined);
 	});
 
 	it("passes model override to onJob", () => {
@@ -138,7 +138,20 @@ describe("Scheduler — cron jobs", () => {
 		s.start();
 		s.stop();
 
-		expect(onJob).toHaveBeenCalledWith("smart", "think hard", "opus");
+		expect(onJob).toHaveBeenCalledWith("smart", "think hard", "opus", undefined, undefined);
+	});
+
+	it("passes chat field to onJob for cron jobs", () => {
+		writeScheduleConfig({
+			jobs: [{ name: "targeted-cron", cron: currentMinuteCron(), prompt: "family update", chat: "family" }],
+		});
+
+		const onJob = makeOnJob();
+		const s = new Scheduler(TEST_DIR, { timeZone: "UTC", onJob });
+		s.start();
+		s.stop();
+
+		expect(onJob).toHaveBeenCalledWith("targeted-cron", "family update", undefined, undefined, "family");
 	});
 
 	it("never removes cron jobs after firing", () => {
@@ -168,7 +181,7 @@ describe("Scheduler — fireAt jobs", () => {
 		s.start();
 		s.stop();
 
-		expect(onJob).toHaveBeenCalledWith("now", "do it", undefined);
+		expect(onJob).toHaveBeenCalledWith("now", "do it", undefined, undefined, undefined);
 		expect(onJob.mock.calls[0][3]).toBeUndefined();
 	});
 
@@ -294,7 +307,7 @@ describe("Scheduler — fireAt jobs", () => {
 		s.start();
 		s.stop();
 
-		expect(onJob).toHaveBeenCalledWith("smart", "think", "opus");
+		expect(onJob).toHaveBeenCalledWith("smart", "think", "opus", undefined, undefined);
 	});
 
 	it("interprets offset-less fireAt in the configured time zone", () => {
@@ -316,7 +329,7 @@ describe("Scheduler — fireAt jobs", () => {
 		s.start();
 		s.stop();
 
-		expect(onJob).toHaveBeenCalledWith("local", "local time", undefined);
+		expect(onJob).toHaveBeenCalledWith("local", "local time", undefined, undefined, undefined);
 	});
 
 	it("preserves explicit offset in fireAt (ignores configured time zone)", () => {
@@ -330,7 +343,20 @@ describe("Scheduler — fireAt jobs", () => {
 		s.start();
 		s.stop();
 
-		expect(onJob).toHaveBeenCalledWith("explicit", "with offset", undefined);
+		expect(onJob).toHaveBeenCalledWith("explicit", "with offset", undefined, undefined, undefined);
+	});
+
+	it("passes chat field to onJob", () => {
+		writeScheduleConfig({
+			jobs: [{ name: "targeted", fireAt: justNowFireAt(), prompt: "hi family", chat: "family" }],
+		});
+
+		const onJob = makeOnJob();
+		const s = new Scheduler(TEST_DIR, { timeZone: "UTC", onJob });
+		s.start();
+		s.stop();
+
+		expect(onJob).toHaveBeenCalledWith("targeted", "hi family", undefined, undefined, "family");
 	});
 
 	it("still fires when write-back of schedule.json fails", () => {

package/src/scheduler.ts

@@ -13,6 +13,7 @@ const jobSchema = z.object({
 	model: z.string().optional(),
 	cron: z.string().optional(),
 	fireAt: z.string().optional(),
+	chat: z.string().optional(),
 });
 
 const scheduleConfigSchema = z.object({
@@ -29,7 +30,7 @@ export interface MissedInfo {
 
 export interface SchedulerConfig {
 	timeZone: string;
-	onJob: (name: string, prompt: string, model?: string, missed?: MissedInfo) => void;
+	onJob: (name: string, prompt: string, model?: string, missed?: MissedInfo, chat?: string) => void;
 }
 
 const TICK_INTERVAL = 10_000; // 10 seconds
@@ -118,14 +119,14 @@ export class Scheduler {
 		}
 	}
 
-	#evaluateCronJob(job: { name: string; cron: string; prompt: string; model?: string }, now: Date): void {
+	#evaluateCronJob(job: { name: string; cron: string; prompt: string; model?: string; chat?: string }, now: Date): void {
 		try {
 			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) {
 				log.debug({ name: job.name, cron: job.cron }, "Cron job triggered");
-				this.#config.onJob(job.name, job.prompt, job.model);
+				this.#config.onJob(job.name, job.prompt, job.model, undefined, job.chat);
 			}
 		} catch (err) {
 			log.warn({ cron: job.cron, err: err instanceof Error ? err.message : err }, "Invalid cron expression");
@@ -144,7 +145,7 @@ export class Scheduler {
 	}
 
 	#evaluateFireAtJob(
-		job: { name: string; fireAt: string; prompt: string; model?: string },
+		job: { name: string; fireAt: string; prompt: string; model?: string; chat?: string },
 		now: Date,
 	): "remove" | "keep" {
 		const fireAt = Scheduler.#parseFireAt(job.fireAt, this.#timeZone);
@@ -162,7 +163,7 @@ export class Scheduler {
 
 		if (diff < 60_000) {
 			log.debug({ name: job.name, fireAt: job.fireAt }, "One-shot job triggered");
-			this.#config.onJob(job.name, job.prompt, job.model);
+			this.#config.onJob(job.name, job.prompt, job.model, undefined, job.chat);
 			return "remove";
 		}
 
@@ -172,7 +173,7 @@ export class Scheduler {
 			this.#config.onJob(job.name, job.prompt, job.model, {
 				missedBy: `${missedMinutes}m`,
 				scheduledAt: job.fireAt,
-			});
+			}, job.chat);
 			return "remove";
 		}
 

package/src/sessions.test.ts

@@ -1,7 +1,14 @@
 import { afterEach, beforeEach, describe, expect, it } from "bun:test";
-import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { loadSessions, newSessionId, saveSessions } from "./sessions";
+import {
+  clearMainSession,
+  getMainSession,
+  loadSessions,
+  newSessionId,
+  saveSessions,
+  setMainSession,
+} from "./sessions";
 
 const tmpDir = "/tmp/macroclaw-sessions-test";
 
@@ -13,46 +20,105 @@ beforeEach(cleanup);
 afterEach(cleanup);
 
 describe("loadSessions", () => {
-  it("returns empty object when dir does not exist", () => {
-    expect(loadSessions(tmpDir)).toEqual({});
+  it("returns empty sessions when dir does not exist", () => {
+    expect(loadSessions(tmpDir)).toEqual({ mainSessions: {} });
   });
 
-  it("returns empty object when file does not exist", () => {
+  it("returns empty sessions when file does not exist", () => {
     mkdirSync(tmpDir, { recursive: true });
-    expect(loadSessions(tmpDir)).toEqual({});
+    expect(loadSessions(tmpDir)).toEqual({ mainSessions: {} });
   });
 
   it("reads sessions from file", () => {
     mkdirSync(tmpDir, { recursive: true });
-    writeFileSync(join(tmpDir, "sessions.json"), JSON.stringify({ mainSessionId: "abc-123" }));
-    expect(loadSessions(tmpDir)).toEqual({ mainSessionId: "abc-123" });
+    writeFileSync(
+      join(tmpDir, "sessions.json"),
+      JSON.stringify({ mainSessions: { admin: "abc-123", family: "def-456" } }),
+    );
+    expect(loadSessions(tmpDir)).toEqual({
+      mainSessions: { admin: "abc-123", family: "def-456" },
+    });
   });
 
-  it("returns empty object when file is corrupt", () => {
+  it("returns empty sessions when file is corrupt", () => {
     mkdirSync(tmpDir, { recursive: true });
     writeFileSync(join(tmpDir, "sessions.json"), "not json");
-    expect(loadSessions(tmpDir)).toEqual({});
+    expect(loadSessions(tmpDir)).toEqual({ mainSessions: {} });
   });
 
   it("strips unknown fields via schema", () => {
     mkdirSync(tmpDir, { recursive: true });
-    writeFileSync(join(tmpDir, "sessions.json"), JSON.stringify({ mainSessionId: "abc", extra: true }));
-    const result = loadSessions(tmpDir);
-    expect(result).toEqual({ mainSessionId: "abc" });
+    writeFileSync(
+      join(tmpDir, "sessions.json"),
+      JSON.stringify({ mainSessions: { admin: "abc" }, extra: true }),
+    );
+    expect(loadSessions(tmpDir)).toEqual({ mainSessions: { admin: "abc" } });
+  });
+
+  it("migrates legacy mainSessionId to mainSessions.admin", () => {
+    mkdirSync(tmpDir, { recursive: true });
+    writeFileSync(join(tmpDir, "sessions.json"), JSON.stringify({ mainSessionId: "legacy-id" }));
+    expect(loadSessions(tmpDir)).toEqual({ mainSessions: { admin: "legacy-id" } });
+  });
+
+  it("defaults to empty mainSessions when field is missing", () => {
+    mkdirSync(tmpDir, { recursive: true });
+    writeFileSync(join(tmpDir, "sessions.json"), JSON.stringify({}));
+    expect(loadSessions(tmpDir)).toEqual({ mainSessions: {} });
   });
 });
 
 describe("saveSessions", () => {
   it("creates directory and writes file", () => {
-    saveSessions({ mainSessionId: "new-id" }, tmpDir);
-    const saved = loadSessions(tmpDir);
-    expect(saved).toEqual({ mainSessionId: "new-id" });
+    saveSessions({ mainSessions: { admin: "new-id" } }, tmpDir);
+    expect(loadSessions(tmpDir)).toEqual({ mainSessions: { admin: "new-id" } });
   });
 
   it("overwrites existing file", () => {
-    saveSessions({ mainSessionId: "first" }, tmpDir);
-    saveSessions({ mainSessionId: "second" }, tmpDir);
-    expect(loadSessions(tmpDir)).toEqual({ mainSessionId: "second" });
+    saveSessions({ mainSessions: { admin: "first" } }, tmpDir);
+    saveSessions({ mainSessions: { admin: "second" } }, tmpDir);
+    expect(loadSessions(tmpDir)).toEqual({ mainSessions: { admin: "second" } });
+  });
+});
+
+describe("getMainSession / setMainSession / clearMainSession", () => {
+  it("returns undefined when no session for chat", () => {
+    expect(getMainSession("admin", tmpDir)).toBeUndefined();
+  });
+
+  it("returns stored session id", () => {
+    saveSessions({ mainSessions: { admin: "abc", family: "def" } }, tmpDir);
+    expect(getMainSession("admin", tmpDir)).toBe("abc");
+    expect(getMainSession("family", tmpDir)).toBe("def");
+  });
+
+  it("setMainSession preserves other chats", () => {
+    saveSessions({ mainSessions: { admin: "abc", family: "def" } }, tmpDir);
+    setMainSession("admin", "new-admin-id", tmpDir);
+    expect(loadSessions(tmpDir)).toEqual({
+      mainSessions: { admin: "new-admin-id", family: "def" },
+    });
+  });
+
+  it("setMainSession adds new chat without touching others", () => {
+    saveSessions({ mainSessions: { admin: "abc" } }, tmpDir);
+    setMainSession("work", "work-id", tmpDir);
+    expect(loadSessions(tmpDir)).toEqual({
+      mainSessions: { admin: "abc", work: "work-id" },
+    });
+  });
+
+  it("clearMainSession removes one chat, preserves others", () => {
+    saveSessions({ mainSessions: { admin: "abc", family: "def" } }, tmpDir);
+    clearMainSession("family", tmpDir);
+    expect(loadSessions(tmpDir)).toEqual({ mainSessions: { admin: "abc" } });
+  });
+
+  it("clearMainSession is a no-op when chat is not present", () => {
+    saveSessions({ mainSessions: { admin: "abc" } }, tmpDir);
+    clearMainSession("nobody", tmpDir);
+    const contents = readFileSync(join(tmpDir, "sessions.json"), "utf-8");
+    expect(JSON.parse(contents)).toEqual({ mainSessions: { admin: "abc" } });
   });
 });
 

package/src/sessions.ts

@@ -7,22 +7,32 @@ import { createLogger } from "./logger";
 const log = createLogger("sessions");
 
 const sessionsSchema = z.object({
-  mainSessionId: z.string().optional(),
+  mainSessions: z.record(z.string(), z.string()).default({}),
 });
 
 export type Sessions = z.infer<typeof sessionsSchema>;
 
 const defaultDir = resolve(process.env.HOME || "~", ".macroclaw");
 
+function migrateLegacy(raw: unknown): unknown {
+  if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+    const obj = raw as Record<string, unknown>;
+    if (typeof obj.mainSessionId === "string" && obj.mainSessions === undefined) {
+      return { mainSessions: { admin: obj.mainSessionId } };
+    }
+  }
+  return raw;
+}
+
 export function loadSessions(dir: string = defaultDir): Sessions {
   try {
     const path = join(dir, "sessions.json");
-    if (!existsSync(path)) return {};
-    const raw = readFileSync(path, "utf-8");
-    return sessionsSchema.parse(JSON.parse(raw));
+    if (!existsSync(path)) return { mainSessions: {} };
+    const raw = migrateLegacy(JSON.parse(readFileSync(path, "utf-8")));
+    return sessionsSchema.parse(raw);
   } catch (err) {
     log.warn({ err }, "Failed to load sessions.json, resetting to empty");
-    return {};
+    return { mainSessions: {} };
   }
 }
 
@@ -31,6 +41,24 @@ export function saveSessions(sessions: Sessions, dir: string = defaultDir): void
   writeFileSync(join(dir, "sessions.json"), `${JSON.stringify(sessions, null, 2)}\n`);
 }
 
+export function getMainSession(chatName: string, dir: string = defaultDir): string | undefined {
+  return loadSessions(dir).mainSessions[chatName];
+}
+
+export function setMainSession(chatName: string, sessionId: string, dir: string = defaultDir): void {
+  const sessions = loadSessions(dir);
+  sessions.mainSessions[chatName] = sessionId;
+  saveSessions(sessions, dir);
+}
+
+export function clearMainSession(chatName: string, dir: string = defaultDir): void {
+  const sessions = loadSessions(dir);
+  if (chatName in sessions.mainSessions) {
+    delete sessions.mainSessions[chatName];
+    saveSessions(sessions, dir);
+  }
+}
+
 export function newSessionId(): string {
   return randomUUID();
 }

package/src/settings.test.ts

@@ -7,7 +7,7 @@ const tmpDir = "/tmp/macroclaw-settings-test";
 
 const validSettings: Settings = {
   botToken: "123:ABC",
-  chatId: "12345678",
+  adminChatId: "12345678",
   model: "sonnet",
   workspace: "~/.macroclaw-workspace",
   timeZone: "UTC",
@@ -32,12 +32,12 @@ describe("SettingsManager.load", () => {
     mkdirSync(tmpDir, { recursive: true });
     writeFileSync(join(tmpDir, "settings.json"), JSON.stringify({
       botToken: "123:ABC",
-      chatId: "12345678",
+      adminChatId: "12345678",
     }));
     const settings = new SettingsManager(tmpDir).load();
     expect(settings).toEqual({
       botToken: "123:ABC",
-      chatId: "12345678",
+      adminChatId: "12345678",
       model: "sonnet",
       workspace: "~/.macroclaw-workspace",
       timeZone: "UTC",
@@ -49,7 +49,7 @@ describe("SettingsManager.load", () => {
     mkdirSync(tmpDir, { recursive: true });
     writeFileSync(join(tmpDir, "settings.json"), JSON.stringify({
       botToken: "  123:ABC  ",
-      chatId: " 12345678 ",
+      adminChatId: " 12345678 ",
       model: " opus ",
       workspace: "  /custom/workspace  ",
       timeZone: "  Europe/Prague  ",
@@ -60,7 +60,7 @@ describe("SettingsManager.load", () => {
     const settings = new SettingsManager(tmpDir).load();
     expect(settings).toEqual({
       botToken: "123:ABC",
-      chatId: "12345678",
+      adminChatId: "12345678",
       model: "opus",
       workspace: "/custom/workspace",
       timeZone: "Europe/Prague",
@@ -74,7 +74,7 @@ describe("SettingsManager.load", () => {
     mkdirSync(tmpDir, { recursive: true });
     writeFileSync(join(tmpDir, "settings.json"), JSON.stringify({
       botToken: "tok",
-      chatId: "123",
+      adminChatId: "123",
       model: "opus",
       workspace: "/custom",
       openaiApiKey: "sk-test",
@@ -84,7 +84,7 @@ describe("SettingsManager.load", () => {
     const settings = new SettingsManager(tmpDir).load();
     expect(settings).toEqual({
       botToken: "tok",
-      chatId: "123",
+      adminChatId: "123",
       model: "opus",
       workspace: "/custom",
       timeZone: "UTC",
@@ -114,7 +114,7 @@ describe("SettingsManager.load", () => {
 
   it("exits with code 1 when validation fails (missing required field)", () => {
     mkdirSync(tmpDir, { recursive: true });
-    writeFileSync(join(tmpDir, "settings.json"), JSON.stringify({ chatId: "123" }));
+    writeFileSync(join(tmpDir, "settings.json"), JSON.stringify({ adminChatId: "123" }));
 
     const mockExit = mock(() => { throw new Error("exit"); });
     const origExit = process.exit;
@@ -134,7 +134,7 @@ describe("SettingsManager.load", () => {
     mkdirSync(tmpDir, { recursive: true });
     writeFileSync(join(tmpDir, "settings.json"), JSON.stringify({
       botToken: "tok",
-      chatId: "123",
+      adminChatId: "123",
       logLevel: "verbose",
     }));
 
@@ -156,7 +156,7 @@ describe("SettingsManager.load", () => {
     mkdirSync(tmpDir, { recursive: true });
     writeFileSync(join(tmpDir, "settings.json"), JSON.stringify({
       botToken: "tok",
-      chatId: "123",
+      adminChatId: "123",
       timeZone: "Europe/Prgaaue",
     }));
 
@@ -199,8 +199,14 @@ describe("SettingsManager.loadRaw", () => {
 
   it("reads and parses valid settings file", () => {
     mkdirSync(tmpDir, { recursive: true });
-    writeFileSync(join(tmpDir, "settings.json"), JSON.stringify({ botToken: "tok", chatId: "123" }));
-    expect(new SettingsManager(tmpDir).loadRaw()).toEqual({ botToken: "tok", chatId: "123" });
+    writeFileSync(join(tmpDir, "settings.json"), JSON.stringify({ botToken: "tok", adminChatId: "123" }));
+    expect(new SettingsManager(tmpDir).loadRaw()).toEqual({ botToken: "tok", adminChatId: "123" });
+  });
+
+  it("migrates legacy chatId to adminChatId", () => {
+    mkdirSync(tmpDir, { recursive: true });
+    writeFileSync(join(tmpDir, "settings.json"), JSON.stringify({ botToken: "tok", chatId: "legacy-id" }));
+    expect(new SettingsManager(tmpDir).loadRaw()).toEqual({ botToken: "tok", adminChatId: "legacy-id" });
   });
 
   it("returns null for invalid JSON", () => {
@@ -218,7 +224,7 @@ describe("SettingsManager.loadRaw", () => {
 
 describe("SettingsManager.applyEnvOverrides", () => {
   const envVars = [
-    "TELEGRAM_BOT_TOKEN", "AUTHORIZED_CHAT_ID", "MODEL",
+    "TELEGRAM_BOT_TOKEN", "ADMIN_CHAT_ID", "AUTHORIZED_CHAT_ID", "MODEL",
     "WORKSPACE", "TIMEZONE", "OPENAI_API_KEY", "LOG_LEVEL", "PINORAMA_URL",
   ];
   const savedEnv: Record<string, string | undefined> = {};
@@ -252,15 +258,29 @@ describe("SettingsManager.applyEnvOverrides", () => {
 
   it("overrides multiple fields and tracks them", () => {
     process.env.TELEGRAM_BOT_TOKEN = "override-token";
-    process.env.AUTHORIZED_CHAT_ID = "99999";
+    process.env.ADMIN_CHAT_ID = "99999";
     process.env.OPENAI_API_KEY = "sk-override";
     const { settings, overrides } = new SettingsManager(tmpDir).applyEnvOverrides(validSettings);
     expect(settings.botToken).toBe("override-token");
-    expect(settings.chatId).toBe("99999");
+    expect(settings.adminChatId).toBe("99999");
     expect(settings.openaiApiKey).toBe("sk-override");
     expect(overrides.size).toBe(3);
   });
 
+  it("falls back to legacy AUTHORIZED_CHAT_ID when ADMIN_CHAT_ID is unset", () => {
+    process.env.AUTHORIZED_CHAT_ID = "88888";
+    const { settings, overrides } = new SettingsManager(tmpDir).applyEnvOverrides(validSettings);
+    expect(settings.adminChatId).toBe("88888");
+    expect(overrides.has("adminChatId")).toBe(true);
+  });
+
+  it("prefers ADMIN_CHAT_ID over legacy AUTHORIZED_CHAT_ID when both set", () => {
+    process.env.ADMIN_CHAT_ID = "111";
+    process.env.AUTHORIZED_CHAT_ID = "222";
+    const { settings } = new SettingsManager(tmpDir).applyEnvOverrides(validSettings);
+    expect(settings.adminChatId).toBe("111");
+  });
+
   it("overrides workspace and log-related fields", () => {
     process.env.WORKSPACE = "/override/path";
     process.env.LOG_LEVEL = "error";
@@ -332,7 +352,11 @@ describe("SettingsManager.print", () => {
 describe("SettingsManager.envMapping", () => {
   it("is a static property with all settings keys", () => {
     expect(SettingsManager.envMapping.botToken).toBe("TELEGRAM_BOT_TOKEN");
-    expect(SettingsManager.envMapping.chatId).toBe("AUTHORIZED_CHAT_ID");
+    expect(SettingsManager.envMapping.adminChatId).toBe("ADMIN_CHAT_ID");
     expect(SettingsManager.envMapping.model).toBe("MODEL");
   });
+
+  it("maps legacy AUTHORIZED_CHAT_ID to adminChatId for migration", () => {
+    expect(SettingsManager.envLegacy.adminChatId).toBe("AUTHORIZED_CHAT_ID");
+  });
 });

package/src/settings.ts

@@ -8,7 +8,7 @@ const log = createLogger("settings");
 
 export const settingsSchema = z.object({
   botToken: z.string().trim(),
-  chatId: z.string().trim().regex(/^-?\d+$/, "Must be a numeric Telegram chat ID"),
+  adminChatId: z.string().trim().regex(/^-?\d+$/, "Must be a numeric Telegram chat ID"),
   model: z.string().trim().pipe(z.enum(["haiku", "sonnet", "opus"])).default("sonnet"),
   workspace: z.string().trim().default("~/.macroclaw-workspace"),
   timeZone: z.string().trim().refine((tz) => IANAZone.isValidZone(tz), "Must be a valid IANA timezone").default("UTC"),
@@ -29,12 +29,24 @@ export function maskValue(key: string, value: string | undefined): string {
 
 const defaultDir = resolve(process.env.HOME || "~", ".macroclaw");
 
+function migrateLegacy(raw: unknown): unknown {
+  if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+    const obj = raw as Record<string, unknown>;
+    if (typeof obj.chatId === "string" && obj.adminChatId === undefined) {
+      const { chatId, ...rest } = obj;
+      log.warn("settings.json uses legacy `chatId` field; migrating to `adminChatId`");
+      return { ...rest, adminChatId: chatId };
+    }
+  }
+  return raw;
+}
+
 export class SettingsManager {
   readonly #dir: string;
 
   static readonly envMapping: Record<keyof Settings, string> = {
     botToken: "TELEGRAM_BOT_TOKEN",
-    chatId: "AUTHORIZED_CHAT_ID",
+    adminChatId: "ADMIN_CHAT_ID",
     model: "MODEL",
     workspace: "WORKSPACE",
     timeZone: "TIMEZONE",
@@ -43,6 +55,11 @@ export class SettingsManager {
     pinoramaUrl: "PINORAMA_URL",
   };
 
+  /** Legacy env var names still honored as fallbacks for one release. */
+  static readonly envLegacy: Partial<Record<keyof Settings, string>> = {
+    adminChatId: "AUTHORIZED_CHAT_ID",
+  };
+
   constructor(dir: string = defaultDir) {
     this.#dir = dir;
   }
@@ -60,7 +77,7 @@ export class SettingsManager {
 
     let raw: unknown;
     try {
-      raw = JSON.parse(readFileSync(path, "utf-8"));
+      raw = migrateLegacy(JSON.parse(readFileSync(path, "utf-8")));
     } catch {
       raw = null;
     }
@@ -78,8 +95,8 @@ export class SettingsManager {
     const path = join(this.#dir, "settings.json");
     if (!existsSync(path)) return null;
     try {
-      const raw = JSON.parse(readFileSync(path, "utf-8"));
-      return typeof raw === "object" && raw !== null ? raw : null;
+      const raw = migrateLegacy(JSON.parse(readFileSync(path, "utf-8")));
+      return typeof raw === "object" && raw !== null ? (raw as Record<string, unknown>) : null;
     } catch {
       return null;
     }
@@ -99,6 +116,13 @@ export class SettingsManager {
       if (value !== undefined) {
         merged[key] = value;
         overrides.add(key);
+        continue;
+      }
+      const legacy = SettingsManager.envLegacy[key as keyof Settings];
+      if (legacy && process.env[legacy] !== undefined) {
+        merged[key] = process.env[legacy];
+        overrides.add(key);
+        log.warn({ legacy, preferred: envVar }, "using legacy env var; rename to the new one");
       }
     }
 

package/src/setup.test.ts

@@ -46,6 +46,12 @@ mock.module("grammy", () => ({
       await mockBotStop();
     }
   },
+  InlineKeyboard: class {
+    inline_keyboard: never[] = [];
+    text() { return this; }
+    row() { return this; }
+  },
+  InputFile: class { constructor(public path: string) {} },
 }));
 
 const mockInstall = mock(() => "tail -f /mock/logs");
@@ -79,7 +85,7 @@ function createMockIO(inputs: string[]): SetupIo & { written: string[] } {
 }
 
 // Save/restore env vars
-const envVars = ["TELEGRAM_BOT_TOKEN", "AUTHORIZED_CHAT_ID", "MODEL", "WORKSPACE", "TIMEZONE", "OPENAI_API_KEY", "LOG_LEVEL"];
+const envVars = ["TELEGRAM_BOT_TOKEN", "ADMIN_CHAT_ID", "MODEL", "WORKSPACE", "TIMEZONE", "OPENAI_API_KEY", "LOG_LEVEL"];
 const savedEnv: Record<string, string | undefined> = {};
 
 beforeEach(() => {
@@ -119,7 +125,7 @@ describe("SetupWizard", () => {
     const settings = await runSetup(io);
 
     expect(settings.botToken).toBe("123:ABC");
-    expect(settings.chatId).toBe("12345678");
+    expect(settings.adminChatId).toBe("12345678");
     expect(settings.model).toBe("opus");
     expect(settings.workspace).toBe("/my/ws");
     expect(settings.timeZone).toBe("Europe/Prague");
@@ -129,7 +135,7 @@ describe("SetupWizard", () => {
 
   it("uses defaults from env vars when user presses enter", async () => {
     process.env.TELEGRAM_BOT_TOKEN = "env-token";
-    process.env.AUTHORIZED_CHAT_ID = "99887766";
+    process.env.ADMIN_CHAT_ID = "99887766";
     process.env.MODEL = "haiku";
     process.env.WORKSPACE = "/env/ws";
     process.env.TIMEZONE = "America/New_York";
@@ -148,7 +154,7 @@ describe("SetupWizard", () => {
     const settings = await runSetup(io);
 
     expect(settings.botToken).toBe("env-token");
-    expect(settings.chatId).toBe("99887766");
+    expect(settings.adminChatId).toBe("99887766");
     expect(settings.model).toBe("haiku");
     expect(settings.workspace).toBe("/env/ws");
     expect(settings.timeZone).toBe("America/New_York");
@@ -246,7 +252,7 @@ describe("SetupWizard", () => {
 
     const settings = await runSetup(io);
 
-    expect(settings.chatId).toBe("456");
+    expect(settings.adminChatId).toBe("456");
   });
 
   it("re-prompts when chat ID is not numeric", async () => {
@@ -263,7 +269,7 @@ describe("SetupWizard", () => {
 
     const settings = await runSetup(io);
 
-    expect(settings.chatId).toBe("456");
+    expect(settings.adminChatId).toBe("456");
     expect(io.written).toContainEqual(expect.stringContaining("Invalid value"));
   });