macroclaw 0.17.0 → 0.19.0

package/README.md

@@ -9,7 +9,7 @@ A lightweight bridge that turns a Telegram chat into a personal AI assistant —
 Macroclaw runs with `dangerouslySkipPermissions` enabled. This is intentional — the bot
 is designed to run in an isolated environment (container or VM) where the workspace is
 the entire world. The single authorized chat ID ensures only one user can interact with
-the bot.
+the bot. See [Docker](#docker) for the recommended containerized setup.
 
 ## Requirements
 
@@ -55,6 +55,8 @@ Session state (Claude session IDs) is stored separately in `~/.macroclaw/session
 
 ## Commands
 
+Run `macroclaw --help` or `macroclaw <command> --help` for the complete reference.
+
 | Command | Description |
 |---------|-------------|
 | `macroclaw start` | Start the bridge |
@@ -80,6 +82,43 @@ Both paths install macroclaw globally via `bun install -g`, register it as a **l
 
 On Linux, the command runs as a normal user. Only the privileged operations (writing to `/etc/systemd/system/`, systemctl commands) are elevated via `sudo`, which prompts for a password when needed. Package installation and path resolution stay in the user's environment.
 
+## Docker
+
+Run macroclaw in a Docker container. The workspace is bind-mounted from the host; everything else (settings, Claude auth, sessions) lives in a named Docker volume.
+
+```bash
+# 1. Login to Claude Code (one-time, interactive — use /login inside the session)
+docker compose run --rm -w /workspace --entrypoint claude macroclaw
+
+# 2. Setup macroclaw (one-time, interactive — bot token, chat ID, model)
+docker compose run --rm macroclaw setup --skip-service
+
+# 3. Start the bridge
+docker compose up -d
+```
+
+The `WORKSPACE` env var is pre-set in `docker-compose.yml` so you don't need to configure the workspace path during setup. The `--skip-service` flag skips the service installation prompt (not applicable in Docker).
+
+To build a specific version:
+
+```bash
+docker compose build --build-arg VERSION=0.18.0
+```
+
+To reset everything (remove containers, volumes, and images):
+
+```bash
+docker compose down -v --rmi all
+```
+
+### Development with Docker
+
+Use `Dockerfile.dev` to build from local source instead of the published npm package:
+
+```bash
+docker compose -f docker-compose.dev.yml up -d
+```
+
 ## Development
 
 ```bash
@@ -118,7 +157,7 @@ Macroclaw follows a **thin platform, rich workspace** design:
 **Workspace** — the intelligence layer, initialized from [`workspace-template/`](workspace-template/):
 - [`CLAUDE.md`](workspace-template/CLAUDE.md) — agent behavior, conventions, response style
 - [`.claude/skills/`](workspace-template/.claude/skills/) — teachable capabilities
-- [`.macroclaw/cron.json`](workspace-template/.macroclaw/cron.json) — scheduled job definitions
+- [`data/schedule.json`](workspace-template/data/schedule.json) — scheduled event definitions
 - [`MEMORY.md`](workspace-template/MEMORY.md) — persistent memory
 
 ### Where does a new feature belong?

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "macroclaw",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "description": "Telegram-to-Claude-Code bridge",
   "license": "MIT",
   "type": "module",

package/src/cli.test.ts

@@ -18,10 +18,11 @@ mock.module("node:child_process", () => ({
 
 const { main } = await import("./cli");
 
-function createMockWizard(overrides?: { collectSettings?: (defaults?: Record<string, unknown>) => Promise<unknown>; installService?: () => Promise<void> }) {
+function createMockWizard(overrides?: { collectSettings?: (defaults?: Record<string, unknown>) => Promise<unknown>; installService?: () => Promise<void>; forceInstallService?: () => Promise<void> }) {
 	return {
 		collectSettings: overrides?.collectSettings ?? mock(async () => ({ botToken: "tok", chatId: "123" })),
 		installService: overrides?.installService ?? mock(async () => {}),
+		forceInstallService: overrides?.forceInstallService ?? mock(async () => {}),
 	} as unknown as SetupWizard;
 }
 
@@ -94,6 +95,23 @@ describe("Cli.setup", () => {
 		expect((wizard.installService as ReturnType<typeof mock>)).toHaveBeenCalled();
 	});
 
+	it("skips service install when --skip-service is set", async () => {
+		const wizard = createMockWizard();
+		const cli = new Cli({ wizard, settings: createMockSettings() });
+		await cli.setup({ skipService: true });
+		expect((wizard.collectSettings as ReturnType<typeof mock>)).toHaveBeenCalled();
+		expect((wizard.installService as ReturnType<typeof mock>)).not.toHaveBeenCalled();
+	});
+
+	it("force installs service when --install-service is set", async () => {
+		const forceInstallService = mock(async () => {});
+		const wizard = { ...createMockWizard(), forceInstallService } as unknown as SetupWizard;
+		const cli = new Cli({ wizard, settings: createMockSettings() });
+		await cli.setup({ installService: true });
+		expect(forceInstallService).toHaveBeenCalled();
+		expect((wizard.installService as ReturnType<typeof mock>)).not.toHaveBeenCalled();
+	});
+
 	it("creates default wizard when none provided", () => {
 		const cli = new Cli({ settings: createMockSettings() });
 		expect(cli).toBeDefined();

package/src/cli.ts

@@ -18,10 +18,15 @@ export class Cli {
 		this.#serviceManager = opts?.systemService ?? new SystemServiceManager();
 	}
 
-	async setup(): Promise<void> {
+	async setup(opts?: { skipService?: boolean; installService?: boolean }): Promise<void> {
 		const defaults = this.#settingsManager.loadRaw() ?? undefined;
 		const settings = await this.#setupWizard.collectSettings(defaults);
 		this.#settingsManager.save(settings);
+		if (opts?.skipService) return;
+		if (opts?.installService) {
+			await this.#setupWizard.forceInstallService();
+			return;
+		}
 		await this.#setupWizard.installService();
 	}
 
@@ -123,7 +128,11 @@ const startCommand = defineCommand({
 
 const setupCommand = defineCommand({
 	meta: { name: "setup", description: "Run the interactive setup wizard" },
-	run: () => defaultCli.setup().catch(handleError),
+	args: {
+		"skip-service": { type: "boolean", description: "Skip the service installation prompt" },
+		"install-service": { type: "boolean", description: "Install as a system service without prompting" },
+	},
+	run: ({ args }) => defaultCli.setup({ skipService: args["skip-service"], installService: args["install-service"] }).catch(handleError),
 });
 
 const claudeCommand = defineCommand({

package/src/cron.test.ts

@@ -4,16 +4,16 @@ import { join } from "node:path";
 import { CronScheduler } from "./cron";
 
 const TEST_DIR = join(import.meta.dir, "..", ".test-workspace-cron");
-const CRON_DIR = join(TEST_DIR, ".macroclaw");
-const CRON_FILE = join(CRON_DIR, "cron.json");
+const SCHEDULE_DIR = join(TEST_DIR, "data");
+const SCHEDULE_FILE = join(SCHEDULE_DIR, "schedule.json");
 
-function writeCronConfig(config: any) {
-  mkdirSync(CRON_DIR, { recursive: true });
-  writeFileSync(CRON_FILE, JSON.stringify(config));
+function writeScheduleConfig(config: any) {
+  mkdirSync(SCHEDULE_DIR, { recursive: true });
+  writeFileSync(SCHEDULE_FILE, JSON.stringify(config));
 }
 
-function readCronConfig() {
-  return JSON.parse(readFileSync(CRON_FILE, "utf-8"));
+function readScheduleConfig() {
+  return JSON.parse(readFileSync(SCHEDULE_FILE, "utf-8"));
 }
 
 function makeOnJob() {
@@ -33,8 +33,14 @@ function nonMatchingCron(): string {
   return `${otherMinute} ${(now.getHours() + 12) % 24} * * *`;
 }
 
+// Build a cron expression that matched N minutes ago
+function minutesAgoCron(minutesAgo: number): string {
+  const past = new Date(Date.now() - minutesAgo * 60_000);
+  return `${past.getMinutes()} ${past.getHours()} ${past.getDate()} ${past.getMonth() + 1} *`;
+}
+
 beforeEach(() => {
-  mkdirSync(CRON_DIR, { recursive: true });
+  mkdirSync(SCHEDULE_DIR, { recursive: true });
 });
 
 afterEach(() => {
@@ -43,7 +49,7 @@ afterEach(() => {
 
 describe("CronScheduler", () => {
   it("calls onJob for matching cron job", () => {
-    writeCronConfig({
+    writeScheduleConfig({
       jobs: [{ name: "test-job", cron: currentMinuteCron(), prompt: "do something" }],
     });
 
@@ -56,7 +62,7 @@ describe("CronScheduler", () => {
   });
 
   it("does not call onJob for non-matching jobs", () => {
-    writeCronConfig({
+    writeScheduleConfig({
       jobs: [{ name: "later", cron: nonMatchingCron(), prompt: "not now" }],
     });
 
@@ -68,8 +74,8 @@ describe("CronScheduler", () => {
     expect(onJob).not.toHaveBeenCalled();
   });
 
-  it("silently skips when cron.json does not exist", () => {
-    rmSync(CRON_FILE, { force: true });
+  it("silently skips when schedule.json does not exist", () => {
+    rmSync(SCHEDULE_FILE, { force: true });
 
     const onJob = makeOnJob();
     const cron = new CronScheduler(TEST_DIR, { onJob });
@@ -80,7 +86,7 @@ describe("CronScheduler", () => {
   });
 
   it("does not call onJob on malformed JSON", () => {
-    writeFileSync(CRON_FILE, "not json{{{");
+    writeFileSync(SCHEDULE_FILE, "not json{{{");
 
     const onJob = makeOnJob();
     const cron = new CronScheduler(TEST_DIR, { onJob });
@@ -91,7 +97,7 @@ describe("CronScheduler", () => {
   });
 
   it("does not call onJob when jobs is not an array", () => {
-    writeCronConfig({ jobs: "not-array" });
+    writeScheduleConfig({ jobs: "not-array" });
 
     const onJob = makeOnJob();
     const cron = new CronScheduler(TEST_DIR, { onJob });
@@ -102,7 +108,7 @@ describe("CronScheduler", () => {
   });
 
   it("skips invalid cron expression and processes valid jobs", () => {
-    writeCronConfig({
+    writeScheduleConfig({
       jobs: [
         { name: "bad", cron: "invalid cron", prompt: "bad" },
         { name: "good", cron: currentMinuteCron(), prompt: "good" },
@@ -119,7 +125,7 @@ describe("CronScheduler", () => {
   });
 
   it("stop clears the interval", () => {
-    writeCronConfig({ jobs: [] });
+    writeScheduleConfig({ jobs: [] });
 
     const onJob = makeOnJob();
     const cron = new CronScheduler(TEST_DIR, { onJob });
@@ -128,7 +134,7 @@ describe("CronScheduler", () => {
   });
 
   it("only evaluates once per minute", () => {
-    writeCronConfig({
+    writeScheduleConfig({
       jobs: [{ name: "once", cron: currentMinuteCron(), prompt: "once" }],
     });
 
@@ -149,7 +155,7 @@ describe("CronScheduler", () => {
   });
 
   it("handles multiple matching jobs", () => {
-    writeCronConfig({
+    writeScheduleConfig({
       jobs: [
         { name: "first", cron: currentMinuteCron(), prompt: "first" },
         { name: "second", cron: currentMinuteCron(), prompt: "second" },
@@ -167,7 +173,7 @@ describe("CronScheduler", () => {
   });
 
   it("passes model override to onJob", () => {
-    writeCronConfig({
+    writeScheduleConfig({
       jobs: [{ name: "smart", cron: currentMinuteCron(), prompt: "think hard", model: "opus" }],
     });
 
@@ -180,7 +186,7 @@ describe("CronScheduler", () => {
   });
 
   it("removes non-recurring job after it fires", () => {
-    writeCronConfig({
+    writeScheduleConfig({
       jobs: [
         { name: "once", cron: currentMinuteCron(), prompt: "one-time", recurring: false },
         { name: "always", cron: currentMinuteCron(), prompt: "forever" },
@@ -194,13 +200,13 @@ describe("CronScheduler", () => {
 
     expect(onJob).toHaveBeenCalledTimes(2);
 
-    const updated = readCronConfig();
+    const updated = readScheduleConfig();
     expect(updated.jobs).toHaveLength(1);
     expect(updated.jobs[0].name).toBe("always");
   });
 
   it("keeps recurring jobs (default behavior)", () => {
-    writeCronConfig({
+    writeScheduleConfig({
       jobs: [{ name: "keeper", cron: currentMinuteCron(), prompt: "stay" }],
     });
 
@@ -209,13 +215,13 @@ describe("CronScheduler", () => {
     cron.start();
     cron.stop();
 
-    const updated = readCronConfig();
+    const updated = readScheduleConfig();
     expect(updated.jobs).toHaveLength(1);
     expect(updated.jobs[0].name).toBe("keeper");
   });
 
   it("keeps jobs with recurring: true", () => {
-    writeCronConfig({
+    writeScheduleConfig({
       jobs: [{ name: "explicit", cron: currentMinuteCron(), prompt: "stay", recurring: true }],
     });
 
@@ -224,32 +230,30 @@ describe("CronScheduler", () => {
     cron.start();
     cron.stop();
 
-    const updated = readCronConfig();
+    const updated = readScheduleConfig();
     expect(updated.jobs).toHaveLength(1);
   });
 
-  it("still fires job when write-back of cron.json fails", () => {
-    // Write config to a path that will be read successfully
-    writeCronConfig({
+  it("still fires job when write-back of schedule.json fails", () => {
+    writeScheduleConfig({
       jobs: [{ name: "once", cron: currentMinuteCron(), prompt: "fire", recurring: false }],
     });
 
-    // Make cron.json read-only so writeFileSync fails
     const { chmodSync } = require("node:fs");
-    chmodSync(CRON_FILE, 0o444);
+    chmodSync(SCHEDULE_FILE, 0o444);
 
     const onJob = makeOnJob();
     const cron = new CronScheduler(TEST_DIR, { onJob });
     cron.start();
     cron.stop();
 
-    chmodSync(CRON_FILE, 0o644);
+    chmodSync(SCHEDULE_FILE, 0o644);
 
     expect(onJob).toHaveBeenCalledTimes(1);
   });
 
   it("does not write file when no non-recurring jobs fired", () => {
-    writeCronConfig({
+    writeScheduleConfig({
       jobs: [{ name: "recurring", cron: nonMatchingCron(), prompt: "nope", recurring: false }],
     });
 
@@ -258,8 +262,74 @@ describe("CronScheduler", () => {
     cron.start();
     cron.stop();
 
-    // File should remain unchanged (job still present since it didn't fire)
-    const updated = readCronConfig();
+    const updated = readScheduleConfig();
+    expect(updated.jobs).toHaveLength(1);
+  });
+});
+
+describe("missed non-recurring events", () => {
+  it("fires missed non-recurring job with missed prefix", () => {
+    writeScheduleConfig({
+      jobs: [{ name: "reminder", cron: minutesAgoCron(3), prompt: "buy milk", recurring: false }],
+    });
+
+    const onJob = makeOnJob();
+    const cron = new CronScheduler(TEST_DIR, { onJob });
+    cron.start();
+    cron.stop();
+
+    expect(onJob).toHaveBeenCalledTimes(1);
+    const call = onJob.mock.calls[0];
+    expect(call[0]).toBe("reminder");
+    expect(call[1]).toContain("[missed event, should have fired");
+    expect(call[1]).toContain("min ago at");
+    expect(call[1]).toContain("buy milk");
+  });
+
+  it("removes missed non-recurring job after firing", () => {
+    writeScheduleConfig({
+      jobs: [
+        { name: "missed", cron: minutesAgoCron(3), prompt: "do it", recurring: false },
+        { name: "keeper", cron: nonMatchingCron(), prompt: "stay" },
+      ],
+    });
+
+    const onJob = makeOnJob();
+    const cron = new CronScheduler(TEST_DIR, { onJob });
+    cron.start();
+    cron.stop();
+
+    expect(onJob).toHaveBeenCalledTimes(1);
+    const updated = readScheduleConfig();
+    expect(updated.jobs).toHaveLength(1);
+    expect(updated.jobs[0].name).toBe("keeper");
+  });
+
+  it("does not fire missed recurring jobs", () => {
+    writeScheduleConfig({
+      jobs: [{ name: "recurring", cron: minutesAgoCron(3), prompt: "repeat" }],
+    });
+
+    const onJob = makeOnJob();
+    const cron = new CronScheduler(TEST_DIR, { onJob });
+    cron.start();
+    cron.stop();
+
+    expect(onJob).not.toHaveBeenCalled();
+  });
+
+  it("does not fire non-recurring jobs older than threshold", () => {
+    writeScheduleConfig({
+      jobs: [{ name: "old", cron: minutesAgoCron(10), prompt: "too late", recurring: false }],
+    });
+
+    const onJob = makeOnJob();
+    const cron = new CronScheduler(TEST_DIR, { onJob });
+    cron.start();
+    cron.stop();
+
+    expect(onJob).not.toHaveBeenCalled();
+    const updated = readScheduleConfig();
     expect(updated.jobs).toHaveLength(1);
   });
 });

package/src/cron.ts

@@ -25,15 +25,16 @@ export interface CronSchedulerConfig {
 }
 
 const TICK_INTERVAL = 10_000; // 10 seconds
+const MISSED_THRESHOLD = 300_000; // 5 minutes
 
 export class CronScheduler {
   #lastMinute = -1;
-  #cronPath: string;
+  #schedulePath: string;
   #config: CronSchedulerConfig;
   #timer: Timer | null = null;
 
   constructor(workspace: string, config: CronSchedulerConfig) {
-    this.#cronPath = join(workspace, ".macroclaw", "cron.json");
+    this.#schedulePath = join(workspace, "data", "schedule.json");
     this.#config = config;
   }
 
@@ -59,16 +60,16 @@ export class CronScheduler {
 
     let config: CronConfig;
     try {
-      const raw = readFileSync(this.#cronPath, "utf-8");
+      const raw = readFileSync(this.#schedulePath, "utf-8");
       const parsed = cronConfigSchema.safeParse(JSON.parse(raw));
       if (!parsed.success) {
-        log.warn("cron.json: 'jobs' is not an array");
+        log.warn("schedule.json: 'jobs' is not an array");
         return;
       }
       config = parsed.data;
     } catch (err) {
       if (err instanceof Error && "code" in err && err.code === "ENOENT") return;
-      log.warn({ err: err instanceof Error ? err.message : err }, "Failed to read cron.json");
+      log.warn({ err: err instanceof Error ? err.message : err }, "Failed to read schedule.json");
       return;
     }
 
@@ -87,6 +88,14 @@ export class CronScheduler {
           if (job.recurring === false) {
             firedNonRecurring.push(i);
           }
+        } else if (job.recurring === false && diff < MISSED_THRESHOLD) {
+          // Non-recurring job missed (service was down) — fire with missed prefix
+          const missedMinutes = Math.round(diff / 60_000);
+          const firedAt = prev.toISOString();
+          const missedPrompt = `[missed event, should have fired ${missedMinutes} min ago at ${firedAt}] ${job.prompt}`;
+          log.info({ name: job.name, missedMinutes, firedAt }, "Firing missed non-recurring job");
+          this.#config.onJob(job.name, missedPrompt, job.model);
+          firedNonRecurring.push(i);
         }
       } catch (err) {
         log.warn({ cron: job.cron, err: err instanceof Error ? err.message : err }, "Invalid cron expression");
@@ -99,9 +108,9 @@ export class CronScheduler {
         config.jobs.splice(firedNonRecurring[i], 1);
       }
       try {
-        writeFileSync(this.#cronPath, `${JSON.stringify(config, null, 2)}\n`);
+        writeFileSync(this.#schedulePath, `${JSON.stringify(config, null, 2)}\n`);
       } catch (err) {
-        log.warn({ err: err instanceof Error ? err.message : err }, "Failed to write cron.json");
+        log.warn({ err: err instanceof Error ? err.message : err }, "Failed to write schedule.json");
       }
     }
   }

package/src/prompts.ts

@@ -42,7 +42,7 @@ Send files via files array (absolute paths). Images (.png/.jpg/.jpeg/.gif/.webp)
 Timeouts: user=${fmtMin(MAIN_TIMEOUT)}, cron=${fmtMin(CRON_TIMEOUT)}, background=${fmtMin(BG_TIMEOUT)}. \
 On timeout, task continues in background automatically. Spawn background agents proactively for long tasks.
 
-Cron: jobs in .macroclaw/cron.json (hot-reloaded). Use "silent" when check finds nothing new, "send" when noteworthy.
+Cron: jobs in data/schedule.json (hot-reloaded). 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.`;

package/src/setup.test.ts

@@ -383,6 +383,31 @@ it("installs service when user answers yes", async () => {
     expect(io.written).toContainEqual(expect.stringContaining("Service installation failed: Permission denied"));
   });
 
+  it("forceInstallService installs without prompting", async () => {
+    mockInstall.mockClear();
+    const installer = createMockServiceInstaller();
+    const io = createMockIO([
+      "sk-test-token",  // oauth token (macOS)
+    ]);
+
+    const wizard = new SetupWizard(io, { serviceInstaller: installer, platform: "darwin" });
+    await wizard.forceInstallService();
+
+    expect(mockInstall).toHaveBeenCalled();
+    expect(io.written).toContainEqual(expect.stringContaining("Service installed and started."));
+  });
+
+  it("forceInstallService skips on Linux without prompting", async () => {
+    mockInstall.mockClear();
+    const installer = createMockServiceInstaller();
+    const io = createMockIO([]);
+
+    const wizard = new SetupWizard(io, { serviceInstaller: installer, platform: "linux" });
+    await wizard.forceInstallService();
+
+    expect(mockInstall).toHaveBeenCalled();
+  });
+
   it("fails fast when claude CLI is not found", async () => {
     mockExecSync.mockImplementation(() => { throw new Error("not found"); });
     const io = createMockIO([]);

package/src/setup.ts

@@ -80,7 +80,7 @@ export class SetupWizard {
 
       // Workspace
       this.#io.write("\nThe workspace directory where Claude Code runs — instructions, skills,\n");
-      this.#io.write("memory, and cron definitions all live here.\n\n");
+      this.#io.write("memory, and scheduled events all live here.\n\n");
       const defaultWorkspace = this.#default("workspace", "~/.macroclaw-workspace");
       const workspace = await this.#askValidated("workspace", `Workspace [${defaultWorkspace}]: `, defaultWorkspace);
 
@@ -116,29 +116,42 @@ export class SetupWizard {
       const installAnswer = await this.#io.ask("Install as a system service? [Y/n]: ");
       if (installAnswer.toLowerCase() === "n" || installAnswer.toLowerCase() === "no") return;
 
-      let oauthToken: string | undefined;
-      if (this.#platform === "darwin") {
-        this.#io.write("\nmacOS requires a long-lived OAuth token for the service.\n");
-        this.#io.write("Run `claude setup-token` in another terminal, then paste the token here.\n\n");
-        oauthToken = await this.#io.ask("OAuth token: ");
-        if (!oauthToken) {
-          this.#io.write("No token provided. Skipping service installation.\n");
-          return;
-        }
-      }
+      await this.#doInstallService();
+    } finally {
+      this.#io.close();
+    }
+  }
 
-      try {
-        const svc = this.#serviceInstaller ?? new (await import("./system-service")).SystemServiceManager();
-        const logCmd = svc.install(oauthToken);
-        this.#io.write(`Service installed and started. Check logs:\n  ${logCmd}\n`);
-      } catch (err) {
-        this.#io.write(`Service installation failed: ${(err as Error).message}\n`);
-      }
+  async forceInstallService(): Promise<void> {
+    this.#io.open();
+    try {
+      await this.#doInstallService();
     } finally {
       this.#io.close();
     }
   }
 
+  async #doInstallService(): Promise<void> {
+    let oauthToken: string | undefined;
+    if (this.#platform === "darwin") {
+      this.#io.write("\nmacOS requires a long-lived OAuth token for the service.\n");
+      this.#io.write("Run `claude setup-token` in another terminal, then paste the token here.\n\n");
+      oauthToken = await this.#io.ask("OAuth token: ");
+      if (!oauthToken) {
+        this.#io.write("No token provided. Skipping service installation.\n");
+        return;
+      }
+    }
+
+    try {
+      const svc = this.#serviceInstaller ?? new (await import("./system-service")).SystemServiceManager();
+      const logCmd = svc.install(oauthToken);
+      this.#io.write(`Service installed and started. Check logs:\n  ${logCmd}\n`);
+    } catch (err) {
+      this.#io.write(`Service installation failed: ${(err as Error).message}\n`);
+    }
+  }
+
   async #askValidated(field: SetupField, prompt: string, fallback: string): Promise<string> {
     const schema = settingsSchema.shape[field];
     let value = await this.#io.ask(prompt) || fallback;

package/workspace-template/.claude/skills/schedule/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: schedule
+description: >
+  Schedule events, reminders, and recurring tasks. Use when the user wants to:
+  set a reminder, schedule something for later, create a recurring task,
+  set up a periodic check, automate a prompt on a schedule, or plan a
+  one-time or repeating event at a specific time.
+---
+
+Schedule a new event by adding it to `data/schedule.json`.
+
+## When to use this
+
+- **Reminders**: "remind me to call the dentist tomorrow at 10"
+- **One-time events**: "send the weekly report this Friday at 5pm"
+- **Recurring tasks**: "check my email every 30 minutes"
+- **Periodic prompts**: "give me a morning summary every weekday at 9"
+- **Scheduled checks**: "monitor the deploy status every 5 minutes for the next hour"
+- **Future actions**: "next Monday, ask me how the presentation went"
+
+## How to schedule
+
+1. Read `data/schedule.json` (create with `{"jobs": []}` if missing)
+2. Convert the user's request to a cron expression (see reference below)
+3. **Be proactive about timing**: if the user says "next week" or "tomorrow" without a specific time, pick the best time based on what you know (their routine, calendar, context)
+4. Append the new job to the `jobs` array
+5. Write the updated file
+6. Confirm: what was scheduled, when it will fire, and offer to adjust
+
+## Natural language → cron
+
+Convert user intent to cron expressions. The user's timezone is in their profile (CLAUDE.md/USER.md) — convert to UTC for cron.
+
+Examples:
+- "in 5 minutes" → compute the exact minute/hour, use a one-shot with `recurring: false`
+- "tomorrow at 10am" → `0 8 14 3 *` (if user is UTC+2, March 13), `recurring: false`
+- "every morning" → `0 7 * * *` (adjust for timezone)
+- "every weekday at 9" → `0 7 * * 1-5` (UTC)
+- "next Monday" → specific date cron, `recurring: false`
+- "every 30 minutes" → `*/30 * * * *`
+
+## schedule.json format
+
+```json
+{
+  "jobs": [
+    {
+      "name": "morning-summary",
+      "cron": "0 7 * * 1-5",
+      "prompt": "Give me a morning summary of my tasks"
+    },
+    {
+      "name": "email-check",
+      "cron": "*/30 * * * *",
+      "prompt": "Check if any important emails arrived",
+      "model": "haiku"
+    },
+    {
+      "name": "dentist-reminder",
+      "cron": "0 8 15 3 *",
+      "prompt": "Reminder: call the dentist to reschedule your appointment",
+      "recurring": false
+    }
+  ]
+}
+```
+
+## Job fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | yes | Short kebab-case identifier (e.g. `dentist-reminder`). Appears in the `[Context: cron/<name>]` prefix when fired. |
+| `cron` | yes | Standard cron expression (UTC). See reference below. |
+| `prompt` | yes | The message sent to the agent when the event fires. Write it as a natural instruction. |
+| `recurring` | no | Defaults to `true`. Set to `false` for one-time events — they're automatically removed after firing. |
+| `model` | no | Override the model. Use `haiku` for cheap checks, `opus` for complex reasoning. Omit for default. |
+
+## Cron expression reference (UTC)
+
+```
+┌───────── minute (0-59)
+│ ┌─────── hour (0-23)
+│ │ ┌───── day of month (1-31)
+│ │ │ ┌─── month (1-12)
+│ │ │ │ ┌─ day of week (0-7, 0 and 7 = Sunday)
+│ │ │ │ │
+* * * * *
+```
+
+Common patterns:
+- `0 9 * * *` — daily at 9:00 UTC
+- `0 7 * * 1-5` — weekdays at 7:00 UTC
+- `*/30 * * * *` — every 30 minutes
+- `0 */2 * * *` — every 2 hours
+- `0 9,18 * * *` — at 9:00 and 18:00 UTC
+
+## Notes
+
+- Changes are hot-reloaded — no restart needed
+- File location: `<workspace>/data/schedule.json`
+- One-shot events (`recurring: false`) are cleaned up automatically after firing
+- Missed one-shot events (e.g. service was down) are fired with a `[missed event]` prefix when the service restarts

package/workspace-template/CLAUDE.md

@@ -57,14 +57,14 @@ Don't ask permission. Just do it.
   - bullet points (plain text bullet character)
   - No markdown syntax. No # headings. No [links](url). No *stars*.
 
-## Cron Jobs
+## Scheduled Events
 
-Messages prefixed with `[Tool: cron/<name>]` are automated. The agent decides whether to respond:
+Scheduled events are created by the `schedule` skill and stored in `data/schedule.json`. Messages prefixed with `[Context: cron/<name>]` are automated scheduled events. The agent decides whether to respond:
 
 - **action: "send"** — the response goes to Telegram
 - **action: "silent"** — the response is logged but not sent
 
-Use `silent` when a cron check finds nothing new. Only send when there's something worth reading.
+Use `silent` when a scheduled check finds nothing new. Only send when there's something worth reading.
 
 ## Skills
 
@@ -86,7 +86,7 @@ When creating new skills, always put them in `.claude/skills/` within this works
 Structure:
 - `.claude/skills/` — local agent skills
 - `memory/` — daily logs (YYYY-MM-DD.md)
-- `.macroclaw/cron.json` — scheduled jobs (hot-reloaded, no restart needed) (use add-cron skill to modify)
+- `data/schedule.json` — scheduled events and reminders (hot-reloaded, no restart needed) (use schedule skill to modify)
 
 ## Safety
 

package/workspace-template/.claude/skills/add-cronjob/SKILL.md

@@ -1,77 +0,0 @@
----
-name: add-cronjob
-description: Add a new scheduled cron job. Use when the user wants to schedule a recurring prompt, add a periodic task, or set up automated messages.
----
-
-Add a new cron job to `.macroclaw/cron.json` in this workspace.
-
-## Steps
-
-1. Read the current `.macroclaw/cron.json` file (create it if missing with `{"jobs": []}`)
-2. Ask the user what prompt to run and when (if not already specified)
-3. Build a standard cron expression for the schedule
-4. Append the new job to the `jobs` array
-5. Write the updated file
-6. Confirm what was added and when it will next run
-
-## cron.json format
-
-```json
-{
-  "jobs": [
-    {
-      "name": "morning-summary",
-      "cron": "0 9 * * *",
-      "prompt": "Give me a morning summary of my tasks"
-    },
-    {
-      "name": "email-check",
-      "cron": "*/30 * * * *",
-      "prompt": "Check if any important emails arrived",
-      "model": "haiku"
-    },
-    {
-      "name": "weekly-report",
-      "cron": "0 17 * * 5",
-      "prompt": "Generate a weekly report of completed tasks",
-      "recurring": false
-    }
-  ]
-}
-```
-
-## Job fields
-
-| Field | Required | Description |
-|-------|----------|-------------|
-| `name` | yes | Short identifier for the job. Appears in the `[Tool: cron/<name>]` prefix so the agent knows which job triggered the prompt. Use kebab-case (e.g. `morning-summary`). |
-| `cron` | yes | Standard cron expression defining when the job runs. See reference below. |
-| `prompt` | yes | The message sent to Claude when the job fires. Write it as if you're typing a message in Telegram — the agent will receive and act on it. |
-| `recurring` | no | Whether the job repeats. Defaults to `true`. Set to `false` for one-shot jobs that should fire once and be automatically removed from cron.json. Good for reminders ("remind me to call the dentist tomorrow at 10") or one-time scheduled events ("send the weekly report this Friday"). |
-| `model` | no | Override the model for this specific job. Omit to use the default model (set via `MODEL` in `.env`), which is best for normal interactive tasks. Use `haiku` for cheap/fast routine checks (email polling, status pings). Use `opus` only when the task genuinely needs deeper reasoning. |
-
-## Cron expression reference
-
-```
-┌───────── minute (0-59)
-│ ┌─────── hour (0-23)
-│ │ ┌───── day of month (1-31)
-│ │ │ ┌─── month (1-12)
-│ │ │ │ ┌─ day of week (0-7, 0 and 7 = Sunday)
-│ │ │ │ │
-* * * * *
-```
-
-Common patterns:
-- `0 9 * * *` — daily at 9:00
-- `0 9 * * 1-5` — weekdays at 9:00
-- `*/30 * * * *` — every 30 minutes
-- `0 */2 * * *` — every 2 hours
-- `0 9,18 * * *` — at 9:00 and 18:00
-
-## Notes
-
-- Changes are hot-reloaded — no restart needed
-- File location: `<workspace>/.macroclaw/cron.json`
-- Prompts are injected into the conversation with a `[Tool: cron/<name>]` prefix
-- One-shot jobs (`recurring: false`) are cleaned up automatically after firing